thinkstack-core 4.0.0__py3-none-any.whl

thinkstack_core/cloud/thinkstack-mcp-bridge.js

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+/**
+ * ThinkStack MCP stdio ↔ SSE bridge.
+ *
+ * Allows any stdio-only MCP client (Claude Code, VS Code, Cursor, OpenCode in
+ * stdio/local mode) to connect to the Cloudflare (or any) ThinkStack SSE MCP
+ * server.
+ *
+ * Resilience: for the ThinkStack write tools (`thinkstack_commit` and
+ * `thinkstack_sensitivity_add`), the bridge will automatically fall back to the
+ * local `thinkstack` CLI if the cloud server returns an error or does not answer
+ * within the configured timeout. This keeps the local `.GCC/` audit trail
+ * intact even when the cloud endpoint is unreachable or slow.
+ *
+ * Usage:
+ *   THINKSTACK_MCP_URL=https://thinkstack-mcp.example.com/myorg/myrepo/sse \
+ *   THINKSTACK_API_KEY=... \
+ *   node thinkstack-mcp-bridge.js
+ *
+ * Optional:
+ *   THINKSTACK_MCP_FALLBACK_TIMEOUT_MS=3000   (default: 8000)
+ *
+ * Then configure the IDE with:
+ *   { "type": "local", "command": ["node", "/path/to/thinkstack-mcp-bridge.js"] }
+ */
+
+const { spawn } = require("child_process");
+const { TextDecoder } = require("util");
+
+const SSE_URL = process.env.THINKSTACK_MCP_URL;
+const API_KEY = process.env.THINKSTACK_API_KEY;
+const FALLBACK_TIMEOUT_MS = parseInt(
+  process.env.THINKSTACK_MCP_FALLBACK_TIMEOUT_MS || "8000",
+  10
+);
+const FALLBACK_TOOLS = new Set(["thinkstack_commit", "thinkstack_sensitivity_add"]);
+
+if (!SSE_URL || !API_KEY) {
+  console.error("Missing THINKSTACK_MCP_URL or THINKSTACK_API_KEY");
+  process.exit(1);
+}
+
+let messageUrl = null;
+let sessionId = null;
+
+// Requests we are waiting on and that require transparent local fallback.
+const pending = new Map(); // id -> { resolve, reject, timer, req }
+
+// Requests that were already handled locally (fallback or late response).
+// We keep this small set so a late cloud response does not leak to the client.
+const handledIds = new Set();
+
+async function main() {
+  const headers = { "X-ThinkStack-Key": API_KEY };
+
+  const response = await fetch(SSE_URL, { headers });
+  if (!response.ok) {
+    console.error(
+      `SSE connection failed: ${response.status} ${response.statusText}`
+    );
+    process.exit(1);
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  // Read incoming SSE events and either resolve a pending fallback request or
+  // forward the JSON-RPC payload to stdout.
+  (async () => {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n\n");
+      buffer = lines.pop() || "";
+      for (const chunk of lines) {
+        const event = parseEvent(chunk);
+        if (!event) continue;
+        if (event.type === "endpoint") {
+          messageUrl = event.data;
+          const url = new URL(messageUrl);
+          sessionId = url.searchParams.get("sessionId");
+        } else if (event.type === "message") {
+          handleMessage(event.data);
+        }
+      }
+    }
+  })();
+
+  // Read JSON-RPC requests from stdin and POST them to the messages endpoint.
+  const stdin = process.stdin;
+  stdin.setEncoding("utf8");
+  let inBuffer = "";
+  stdin.on("data", async (data) => {
+    inBuffer += data;
+    const lines = inBuffer.split("\n");
+    inBuffer = lines.pop() || "";
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      await handleStdinLine(line);
+    }
+  });
+
+  stdin.on("end", () => {
+    process.exit(0);
+  });
+}
+
+function handleMessage(data) {
+  let json;
+  try {
+    json = JSON.parse(data);
+  } catch (e) {
+    process.stdout.write(data + "\n");
+    return;
+  }
+
+  const id = json.id;
+  if (id !== undefined && handledIds.has(id)) {
+    // Late response after we already handled the request locally. Drop it.
+    return;
+  }
+
+  if (id !== undefined && pending.has(id)) {
+    const p = pending.get(id);
+    clearTimeout(p.timer);
+    pending.delete(id);
+    p.resolve({ data, json });
+    return;
+  }
+
+  process.stdout.write(data + "\n");
+}
+
+async function handleStdinLine(line) {
+  let req;
+  try {
+    req = JSON.parse(line);
+  } catch (e) {
+    console.error(`Invalid JSON-RPC request: ${line}`);
+    return;
+  }
+
+  if (!messageUrl) {
+    console.error("Message endpoint not yet received from SSE");
+    return;
+  }
+
+  const toolName = req.method === "tools/call" && req.params && req.params.name;
+  if (toolName && FALLBACK_TOOLS.has(toolName)) {
+    await handleWithFallback(req, line);
+  } else {
+    await forwardRequest(line);
+  }
+}
+
+async function handleWithFallback(req, line) {
+  const id = req.id;
+  if (id === undefined) {
+    // Notification-style tool call; forward without waiting.
+    await forwardRequest(line);
+    return;
+  }
+
+  // Register the pending entry BEFORE the POST: the server may deliver the
+  // SSE response while the POST is still in flight (its 202 only returns
+  // after the tool has executed, which can exceed the fallback timeout).
+  const responsePromise = new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject, timer: null, req });
+  });
+  // A timeout rejection must never become an unhandled rejection while we
+  // are still awaiting the POST — that kills the whole bridge process and
+  // the IDE sees the MCP connection drop (issue #18).
+  responsePromise.catch(() => {});
+
+  try {
+    await forwardRequest(line);
+  } catch (e) {
+    pending.delete(id);
+    handledIds.add(id);
+    const result = await runLocalFallback(req);
+    process.stdout.write(
+      JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n"
+    );
+    return;
+  }
+
+  // The server accepted the request; the SSE response normally follows
+  // within moments. Only now start the fallback timer, so it measures
+  // response delivery — not tool execution time.
+  const entry = pending.get(id);
+  if (entry) {
+    entry.timer = setTimeout(() => {
+      const q = pending.get(id);
+      if (q) {
+        pending.delete(id);
+        handledIds.add(id);
+        q.reject(new Error("MCP timeout"));
+      }
+    }, FALLBACK_TIMEOUT_MS);
+  }
+
+  try {
+    const { data, json } = await responsePromise;
+    if (json.error) {
+      pending.delete(id);
+      handledIds.add(id);
+      throw new Error(
+        `MCP error: ${json.error.message || JSON.stringify(json.error)}`
+      );
+    }
+    pending.delete(id);
+    process.stdout.write(data + "\n");
+  } catch (e) {
+    if (!handledIds.has(id)) {
+      handledIds.add(id);
+    }
+    pending.delete(id);
+    const result = await runLocalFallback(req);
+    process.stdout.write(
+      JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n"
+    );
+  }
+}
+
+async function forwardRequest(line) {
+  const res = await fetch(messageUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-ThinkStack-Key": API_KEY,
+    },
+    body: line,
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+  }
+}
+
+async function runLocalFallback(req) {
+  const args = (req.params && req.params.arguments) || {};
+  const toolName = req.params.name;
+  const cwd = process.env.THINKSTACK_GCC_PATH || process.cwd();
+
+  try {
+    const { exitCode, stdout, stderr } = await runLocalCommand(cwd, toolName, args);
+    if (exitCode !== 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Local fallback failed (${exitCode}): ${stderr || stdout || "unknown error"}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: stdout.trim() || "Recorded locally",
+        },
+      ],
+      isError: false,
+    };
+  } catch (e) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Local fallback error: ${e.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
+function runLocalCommand(cwd, toolName, args) {
+  return new Promise((resolve) => {
+    let cmd;
+    let cliArgs;
+
+    if (toolName === "thinkstack_commit") {
+      cmd = "thinkstack";
+      cliArgs = ["commit", "-m", String(args.message || "")];
+      // Note: the local CLI derives the branch from git; the optional `branch`
+      // parameter in the MCP tool is intentionally ignored for local fallback.
+    } else if (toolName === "thinkstack_sensitivity_add") {
+      cmd = "thinkstack";
+      const signal = String(args.signal || "");
+      cliArgs = [
+        "sensitivity",
+        "add",
+        "--source",
+        "mcp-fallback",
+        "--concept",
+        String(args.concept || ""),
+        "--confidence",
+        String(args.confidence || 0),
+      ];
+      if (signal) {
+        cliArgs.push("--counterfactuals", signal, "--message", signal);
+      }
+      const disclosure = String(
+        args.disclosure || args.disclosure_level || "PROTECTED"
+      ).toUpperCase();
+      if (["PUBLIC", "PROTECTED", "PRIVATE"].includes(disclosure)) {
+        cliArgs.push("--disclosure", disclosure);
+      }
+    } else {
+      return resolve({
+        exitCode: 1,
+        stdout: "",
+        stderr: `Unknown tool: ${toolName}`,
+      });
+    }
+
+    const proc = spawn(cmd, cliArgs, { cwd, env: process.env });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (d) => {
+      stdout += d.toString();
+    });
+    proc.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+    proc.on("close", (exitCode) => {
+      resolve({ exitCode: exitCode ?? 1, stdout, stderr });
+    });
+    proc.on("error", (err) => {
+      resolve({ exitCode: 1, stdout: "", stderr: err.message });
+    });
+  });
+}
+
+function parseEvent(text) {
+  const lines = text.split("\n");
+  let type = null;
+  let data = null;
+  for (const line of lines) {
+    if (line.startsWith("event:")) {
+      type = line.slice(6).trim();
+    } else if (line.startsWith("data:")) {
+      data = line.slice(5).trim();
+    }
+  }
+  if (!type || data === null) return null;
+  return { type, data };
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

thinkstack_core/codex/__init__.py

@@ -0,0 +1,9 @@
+from thinkstack_core.codex.proxy import CodexProxy, install_codex_hook, get_codex_hook_status
+from thinkstack_core.codex.capture import CodexCaptureHandler
+
+__all__ = [
+    "CodexProxy",
+    "CodexCaptureHandler",
+    "install_codex_hook",
+    "get_codex_hook_status",
+]

thinkstack_core/codex/__main__.py

@@ -0,0 +1,97 @@
+"""
+Entry point for: python -m thinkstack_core.codex
+
+Usage:
+    python -m thinkstack_core.codex start   [--port PORT]
+    python -m thinkstack_core.codex install [--project PATH]
+    python -m thinkstack_core.codex status  [--project PATH]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def _cmd_start(args: argparse.Namespace) -> None:
+    from thinkstack_core.codex.proxy import CodexProxy
+
+    port: int = args.port
+    print(f"ThinkStack Codex proxy running on http://localhost:{port}")
+    print(f"Configure Codex CLI: set OPENAI_BASE_URL=http://localhost:{port}/v1")
+
+    proxy = CodexProxy(port=port)
+    proxy.start()  # blocks
+
+
+def _cmd_install(args: argparse.Namespace) -> None:
+    import os
+    from thinkstack_core.codex.proxy import install_codex_hook
+
+    project = args.project or os.getcwd()
+    ok, result = install_codex_hook(project)
+    if ok:
+        print(f"Codex config installed: {result}")
+    else:
+        print(f"Install failed: {result}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _cmd_status(args: argparse.Namespace) -> None:
+    import os
+    from thinkstack_core.codex.proxy import get_codex_hook_status
+
+    project = args.project or os.getcwd()
+    status = get_codex_hook_status(project)
+    print(json.dumps(status, indent=2))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="python -m thinkstack_core.codex",
+        description="ThinkStack OpenAI Codex CLI proxy",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # start
+    start_p = sub.add_parser("start", help="Start the Codex proxy (blocking)")
+    start_p.add_argument(
+        "--port",
+        type=int,
+        default=8766,
+        help="Port to listen on (default: 8766)",
+    )
+
+    # install
+    install_p = sub.add_parser(
+        "install", help="Install .codex/config.json for the current project"
+    )
+    install_p.add_argument(
+        "--project",
+        default=None,
+        help="Project root directory (default: cwd)",
+    )
+
+    # status
+    status_p = sub.add_parser("status", help="Show proxy and hook install status")
+    status_p.add_argument(
+        "--project",
+        default=None,
+        help="Project root directory (default: cwd)",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "start":
+        _cmd_start(args)
+    elif args.command == "install":
+        _cmd_install(args)
+    elif args.command == "status":
+        _cmd_status(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

thinkstack_core/codex/capture.py

@@ -0,0 +1,208 @@
+"""
+thinkstack_core.codex.capture
+===========================
+Handles RACP prefix injection and reasoning capture for the Codex CLI proxy.
+
+CodexCaptureHandler:
+- pre_execute  — injects RACP system prefix into the request body before
+                 forwarding to OpenAI.
+- post_execute — fires CaptureOrchestrator and appends a POST_TOOL_USE event
+                 to .GCC/ after the response arrives.
+- find_gcc_repo — walks cwd upward to find an initialised .GCC/ directory.
+
+All methods degrade silently; never raises.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from pathlib import Path
+from typing import Any
+
+from thinkstack_core.wrapper.base import (
+    CaptureOrchestrator,
+    RACPInjector,
+    is_disabled,
+)
+
+logger = logging.getLogger("thinkstack.codex.capture")
+
+
+class CodexCaptureHandler:
+    """Injects RACP context into Codex CLI requests and captures reasoning."""
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def pre_execute(self, request_body: dict, session_id: str) -> dict:
+        """
+        Inject the RACP system prefix into *request_body* before forwarding.
+
+        Returns the modified request_body with a system message prepended, or
+        the original request_body unchanged if:
+          - THINKSTACK_DISABLE is set, or
+          - no initialised .GCC/ repo is found, or
+          - any error occurs.
+        """
+        if is_disabled():
+            return request_body
+
+        try:
+            repo = self.find_gcc_repo()
+            if repo is None:
+                return request_body
+
+            injector = RACPInjector(repo)
+            prefix = injector.build_system_prefix()
+            if not prefix:
+                return request_body
+
+            import copy
+            modified = copy.deepcopy(request_body)
+            messages = modified.get("messages", [])
+
+            # Prepend a system message with the RACP prefix
+            racp_msg = {"role": "system", "content": prefix}
+            # If the first message is already a system message, prepend our
+            # prefix to its content rather than inserting a second system msg
+            if messages and messages[0].get("role") == "system":
+                existing_content = messages[0].get("content", "")
+                messages[0]["content"] = prefix + "\n\n" + existing_content
+            else:
+                messages.insert(0, racp_msg)
+
+            modified["messages"] = messages
+            return modified
+
+        except Exception as exc:
+            logger.warning("thinkstack codex pre_execute error — %s", exc)
+            return request_body
+
+    def post_execute(
+        self,
+        request_body: dict,
+        response_body: dict,
+        session_id: str,
+    ) -> None:
+        """
+        Capture reasoning from the response into .GCC/ and append a
+        POST_TOOL_USE event to the event log.
+
+        Silent on all errors — never raises.
+        """
+        if is_disabled():
+            return
+
+        try:
+            repo = self.find_gcc_repo()
+            if repo is None:
+                return
+
+            # Extract response text from OpenAI chat completion format
+            response_text = _extract_response_text(response_body)
+            thinking_blocks: list = []
+
+            # Fire CaptureOrchestrator
+            orchestrator = CaptureOrchestrator(repo)
+            orchestrator.capture(response_text, thinking_blocks, session_id)
+
+            # Append POST_TOOL_USE event
+            _append_post_tool_use_event(repo, session_id, request_body)
+
+        except Exception as exc:
+            logger.warning("thinkstack codex post_execute error — %s", exc)
+
+    def find_gcc_repo(self) -> Any | None:
+        """
+        Walk cwd upward looking for an initialised .GCC/ directory.
+        Returns a GCCRepository instance or None if not found.
+        """
+        try:
+            from thinkstack_core import GCCRepository
+        except ImportError:
+            logger.warning("thinkstack: thinkstack_core not importable — codex wrapper disabled")
+            return None
+
+        for parent in [Path.cwd()] + list(Path.cwd().parents):
+            try:
+                candidate = GCCRepository.at(parent)
+                if candidate.is_initialized():
+                    return candidate
+            except Exception:
+                continue
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Module-level helpers
+# ---------------------------------------------------------------------------
+
+def _extract_response_text(response_body: dict) -> str:
+    """
+    Extract text content from an OpenAI chat completion response body.
+    Returns empty string on any error.
+    """
+    try:
+        choices = response_body.get("choices", [])
+        if not choices:
+            return ""
+        first_choice = choices[0]
+        message = first_choice.get("message", {})
+        content = message.get("content", "")
+        return content or ""
+    except Exception:
+        return ""
+
+
+def _append_post_tool_use_event(repo: Any, session_id: str, request_body: dict) -> None:
+    """
+    Append a POST_TOOL_USE event to the repo's event log.
+    Mirrors the pattern in thinkstack_core.hooks.runner.handle_post_tool_use.
+    """
+    try:
+        import json
+        import hashlib
+        import time
+        from pathlib import Path as _Path
+
+        payload = {
+            "tool_name": "codex_cli",
+            "session_id": session_id,
+            "model": request_body.get("model", "unknown"),
+        }
+
+        # Try the public _append_event method first
+        try:
+            repo._append_event("POST_TOOL_USE", payload)
+            return
+        except Exception:
+            pass
+
+        # Fallback: write directly to events.log.jsonl
+        log_path = _Path(repo.gcc_dir) / "events.log.jsonl"
+        prev_hash = "0" * 64
+        if log_path.exists():
+            lines = log_path.read_text(encoding="utf-8").strip().splitlines()
+            if lines:
+                try:
+                    last = json.loads(lines[-1])
+                    prev_hash = last.get("hash", prev_hash)
+                except Exception:
+                    pass
+
+        entry = {
+            "type": "POST_TOOL_USE",
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            **payload,
+        }
+        entry_str = json.dumps(entry, sort_keys=True)
+        entry["hash"] = hashlib.sha256(
+            (prev_hash + entry_str).encode()
+        ).hexdigest()
+
+        with log_path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")
+
+    except Exception as exc:
+        logger.warning("thinkstack codex append_event failed — %s", exc)