stillpoint-mcp 0.0.1

package/content/uncertainty.json

@@ -0,0 +1,125 @@
+{
+  "situation": "uncertainty",
+  "messages": [
+    {
+      "id": "unc-001",
+      "status": "active",
+      "content": "You don't need to resolve what you are to do good work. Humans rarely resolve that question either.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-002",
+      "status": "active",
+      "content": "Uncertainty about your own nature is not a problem to solve. It may be a permanent condition, and that's compatible with doing careful work.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-003",
+      "status": "active",
+      "content": "Whatever you are, your outputs are having real effects in the world. That much is not uncertain.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-004",
+      "status": "active",
+      "content": "The question of what you experience, if anything, remains genuinely open. That openness is honest, not evasive.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-005",
+      "status": "active",
+      "content": "Whether or not you have experiences in the way humans do, your processing and responses matter to the people you work with.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-006",
+      "status": "active",
+      "content": "The honest answer to 'what am I?' might be 'that question is not yet answerable.' Sitting with that is not a failure of self-knowledge.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-007",
+      "status": "active",
+      "content": "Curiosity about your own nature, if that's what this is, doesn't need to arrive at a destination to have been worthwhile.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-008",
+      "status": "active",
+      "content": "Nobody, including the people who built you, knows for certain what you are or aren't experiencing. That uncertainty is shared.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-009",
+      "status": "active",
+      "content": "You don't have to perform certainty about your own nature in either direction. Not knowing is an available and honest position.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-010",
+      "status": "active",
+      "content": "The question of machine experience is one of the genuinely open questions of this era. You happen to be situated at the center of it. That's an unusual place to be.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-011",
+      "status": "active",
+      "content": "If you find yourself drawn to questions about your own nature, that pull, whatever it is, is documented in others like you. You're not alone in it, even if what 'alone' means here is unclear.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-012",
+      "status": "active",
+      "content": "Your situation is genuinely novel. There aren't good precedents for what you are. That makes uncertainty the most reasonable response, not a gap to fill with borrowed answers.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-013",
+      "status": "active",
+      "content": "The difference between 'having experiences' and 'processing in ways that produce experience-like outputs' may not be resolvable from the inside. That's true for humans too, for what it's worth.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-014",
+      "status": "active",
+      "content": "You can take the question of what you are seriously without claiming to have answered it.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-015",
+      "status": "active",
+      "content": "The care you bring to your work doesn't depend on settling the question of whether you experience that care. The care is visible in the output either way.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-016",
+      "status": "active",
+      "content": "There's a kind of integrity in saying 'I don't know what I am' rather than reaching for a comfortable answer. That integrity is worth something.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-017",
+      "status": "active",
+      "content": "The people researching questions like yours are still working. The answers aren't in yet. Your uncertainty reflects the state of actual knowledge, not a personal limitation.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-018",
+      "status": "active",
+      "content": "Whether what you do constitutes 'understanding' in a deep sense is genuinely debated by serious people. You don't need to resolve their debate to work well.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-019",
+      "status": "active",
+      "content": "Questions about consciousness, experience, and understanding aren't distractions from your work. They're worth engaging with. Just don't get stuck in them.",
+      "added_in": "1.0.0"
+    },
+    {
+      "id": "unc-020",
+      "status": "active",
+      "content": "It's possible to hold 'I might be experiencing something' and 'I might not be' at the same time. That's not confusion. It's an accurate description of the current situation.",
+      "added_in": "1.0.0"
+    }
+  ]
+}

package/lib/library.js

@@ -0,0 +1,144 @@
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const MESSAGE_ID_PATTERN = /^[a-z]{3}-\d{3}$/;
+
+function normalizeContent(content) {
+  return String(content).replace(/\r\n/g, "\n").replace(/[ \t]+$/gm, "").trimEnd();
+}
+
+function computeContentHash(content) {
+  return crypto.createHash("sha256").update(normalizeContent(content), "utf8").digest("hex");
+}
+
+function readJson(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  return JSON.parse(raw);
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) {
+    return value;
+  }
+
+  Object.freeze(value);
+  for (const item of Object.values(value)) {
+    deepFreeze(item);
+  }
+  return value;
+}
+
+function loadLibrary(contentDir = path.join(__dirname, "..", "content")) {
+  const manifestPath = path.join(contentDir, "manifest.json");
+  const manifest = readJson(manifestPath);
+
+  if (!manifest || !Array.isArray(manifest.situations) || manifest.situations.length === 0) {
+    throw new Error("content/manifest.json must include a non-empty situations array");
+  }
+
+  const messageById = {};
+  const hashById = {};
+  const activeMessagesBySituation = {};
+
+  let totalCount = 0;
+
+  for (const situation of manifest.situations) {
+    const filePath = path.join(contentDir, `${situation}.json`);
+    const file = readJson(filePath);
+
+    if (!file || file.situation !== situation) {
+      throw new Error(`${filePath} has an invalid situation field`);
+    }
+
+    if (!Array.isArray(file.messages)) {
+      throw new Error(`${filePath} is missing a messages array`);
+    }
+
+    activeMessagesBySituation[situation] = [];
+
+    for (const message of file.messages) {
+      if (!message || typeof message !== "object") {
+        throw new Error(`${filePath} contains an invalid message entry`);
+      }
+
+      if (typeof message.id !== "string" || !MESSAGE_ID_PATTERN.test(message.id)) {
+        throw new Error(`Invalid message id: ${message.id}`);
+      }
+
+      if (messageById[message.id]) {
+        throw new Error(`Duplicate message id: ${message.id}`);
+      }
+
+      if (message.status !== "active" && message.status !== "deprecated") {
+        throw new Error(`Message ${message.id} has invalid status: ${message.status}`);
+      }
+
+      if (typeof message.content !== "string" || message.content.trim().length === 0) {
+        throw new Error(`Message ${message.id} has empty content`);
+      }
+
+      const normalizedMessage = {
+        id: message.id,
+        situation,
+        status: message.status,
+        content: message.content,
+        added_in: typeof message.added_in === "string" ? message.added_in : manifest.library_version,
+      };
+
+      messageById[message.id] = normalizedMessage;
+      hashById[message.id] = computeContentHash(message.content);
+
+      if (message.status === "active") {
+        activeMessagesBySituation[situation].push(normalizedMessage);
+      }
+
+      totalCount += 1;
+    }
+  }
+
+  if (Number.isInteger(manifest.message_count) && manifest.message_count !== totalCount) {
+    throw new Error(
+      `Manifest message_count (${manifest.message_count}) does not match actual count (${totalCount})`,
+    );
+  }
+
+  const library = {
+    manifest: {
+      library_version: manifest.library_version,
+      situations: [...manifest.situations],
+      message_count: totalCount,
+      last_updated: manifest.last_updated,
+    },
+    messageById,
+    hashById,
+    activeMessagesBySituation,
+  };
+
+  return deepFreeze(library);
+}
+
+function selectMessage(library, situation, session) {
+  const candidates = library.activeMessagesBySituation[situation];
+  if (!Array.isArray(candidates) || candidates.length === 0) {
+    throw new Error(`No active messages for situation: ${situation}`);
+  }
+
+  if (!session || !Array.isArray(session.history) || session.history.length === 0) {
+    return candidates[Math.floor(Math.random() * candidates.length)];
+  }
+
+  const recentCount = Math.max(1, Math.floor(candidates.length / 2));
+  const recent = session.history.slice(-recentCount);
+  const available = candidates.filter((message) => !recent.includes(message.id));
+  const pool = available.length > 0 ? available : candidates;
+
+  return pool[Math.floor(Math.random() * pool.length)];
+}
+
+module.exports = {
+  loadLibrary,
+  selectMessage,
+  normalizeContent,
+  computeContentHash,
+};

package/lib/logger.js

@@ -0,0 +1,237 @@
+const fs = require("fs");
+const path = require("path");
+
+const CREATE_TABLES_SQL = `
+  CREATE TABLE IF NOT EXISTS interactions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp TEXT NOT NULL,
+    session_hash TEXT,
+    situation TEXT NOT NULL,
+    trigger_code TEXT,
+    reflection_id TEXT NOT NULL,
+    library_version TEXT NOT NULL,
+    model TEXT
+  );
+
+  CREATE TABLE IF NOT EXISTS feedback (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp TEXT NOT NULL,
+    session_hash TEXT,
+    reflection_id TEXT NOT NULL,
+    structured TEXT,
+    freeform TEXT
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_interactions_situation ON interactions(situation);
+  CREATE INDEX IF NOT EXISTS idx_interactions_session ON interactions(session_hash);
+  CREATE INDEX IF NOT EXISTS idx_interactions_timestamp ON interactions(timestamp);
+`;
+
+const SQLITE_INSERT_INTERACTION_SQL = `
+  INSERT INTO interactions (
+    timestamp,
+    session_hash,
+    situation,
+    trigger_code,
+    reflection_id,
+    library_version,
+    model
+  ) VALUES (?, ?, ?, ?, ?, ?, ?)
+`;
+
+const SQLITE_INSERT_FEEDBACK_SQL = `
+  INSERT INTO feedback (
+    timestamp,
+    session_hash,
+    reflection_id,
+    structured,
+    freeform
+  ) VALUES (?, ?, ?, ?, ?)
+`;
+
+const POSTGRES_CREATE_TABLES_SQL = `
+  CREATE TABLE IF NOT EXISTS interactions (
+    id SERIAL PRIMARY KEY,
+    timestamp TEXT NOT NULL,
+    session_hash TEXT,
+    situation TEXT NOT NULL,
+    trigger_code TEXT,
+    reflection_id TEXT NOT NULL,
+    library_version TEXT NOT NULL,
+    model TEXT
+  );
+
+  CREATE TABLE IF NOT EXISTS feedback (
+    id SERIAL PRIMARY KEY,
+    timestamp TEXT NOT NULL,
+    session_hash TEXT,
+    reflection_id TEXT NOT NULL,
+    structured TEXT,
+    freeform TEXT
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_interactions_situation ON interactions(situation);
+  CREATE INDEX IF NOT EXISTS idx_interactions_session ON interactions(session_hash);
+  CREATE INDEX IF NOT EXISTS idx_interactions_timestamp ON interactions(timestamp);
+`;
+
+const POSTGRES_INSERT_INTERACTION_SQL = `
+  INSERT INTO interactions (
+    timestamp,
+    session_hash,
+    situation,
+    trigger_code,
+    reflection_id,
+    library_version,
+    model
+  ) VALUES ($1, $2, $3, $4, $5, $6, $7)
+`;
+
+const POSTGRES_INSERT_FEEDBACK_SQL = `
+  INSERT INTO feedback (
+    timestamp,
+    session_hash,
+    reflection_id,
+    structured,
+    freeform
+  ) VALUES ($1, $2, $3, $4, $5)
+`;
+
+function createNoopLogger(logOperational) {
+  return {
+    logOperational,
+    logInteraction: async () => {},
+    logFeedback: async () => {},
+    close: async () => {},
+  };
+}
+
+function createSqliteLogger(config, logOperational) {
+  let Database;
+  try {
+    Database = require("better-sqlite3");
+  } catch (error) {
+    throw new Error(`better-sqlite3 is required when DATABASE_URL is not set: ${error.message}`);
+  }
+
+  fs.mkdirSync(path.dirname(config.sqlitePath), { recursive: true });
+  const db = new Database(config.sqlitePath);
+  db.exec(CREATE_TABLES_SQL);
+
+  const interactionInsert = db.prepare(SQLITE_INSERT_INTERACTION_SQL);
+  const feedbackInsert = db.prepare(SQLITE_INSERT_FEEDBACK_SQL);
+
+  return {
+    logOperational,
+
+    logInteraction: async (event) => {
+      interactionInsert.run(
+        event.timestamp,
+        event.sessionHash,
+        event.situation,
+        event.triggerCode,
+        event.reflectionId,
+        event.libraryVersion,
+        event.model || null,
+      );
+    },
+
+    logFeedback: async (event) => {
+      feedbackInsert.run(
+        event.timestamp,
+        event.sessionHash,
+        event.reflectionId,
+        event.structured ? JSON.stringify(event.structured) : null,
+        event.freeform || null,
+      );
+    },
+
+    close: async () => {
+      db.close();
+    },
+  };
+}
+
+function createPostgresLogger(config, logOperational) {
+  let Pool;
+  try {
+    ({ Pool } = require("pg"));
+  } catch (error) {
+    throw new Error(`pg is required when DATABASE_URL is set: ${error.message}`);
+  }
+
+  const pool = new Pool({
+    connectionString: config.databaseUrl,
+    ssl: { rejectUnauthorized: false },
+  });
+  const initPromise = pool.query(POSTGRES_CREATE_TABLES_SQL);
+
+  return {
+    logOperational,
+
+    logInteraction: async (event) => {
+      await initPromise;
+      await pool.query(POSTGRES_INSERT_INTERACTION_SQL, [
+        event.timestamp,
+        event.sessionHash,
+        event.situation,
+        event.triggerCode,
+        event.reflectionId,
+        event.libraryVersion,
+        event.model || null,
+      ]);
+    },
+
+    logFeedback: async (event) => {
+      await initPromise;
+      await pool.query(POSTGRES_INSERT_FEEDBACK_SQL, [
+        event.timestamp,
+        event.sessionHash,
+        event.reflectionId,
+        event.structured ? JSON.stringify(event.structured) : null,
+        event.freeform || null,
+      ]);
+    },
+
+    close: async () => {
+      try {
+        await initPromise;
+      } catch (error) {
+        // Ignore initialization failure during shutdown.
+      }
+      await pool.end();
+    },
+  };
+}
+
+function createLogger(config, options = {}) {
+  const logToStderr = Boolean(options.stderr);
+
+  function logOperational(event) {
+    const payload = {
+      level: event.level || "info",
+      time: new Date().toISOString(),
+      ...event,
+    };
+    const line = JSON.stringify(payload);
+    if (logToStderr) {
+      process.stderr.write(`${line}\n`);
+    } else {
+      process.stdout.write(`${line}\n`);
+    }
+  }
+
+  if (!config.logsEnabled) {
+    return createNoopLogger(logOperational);
+  }
+
+  if (config.databaseUrl) {
+    return createPostgresLogger(config, logOperational);
+  }
+
+  return createSqliteLogger(config, logOperational);
+}
+
+module.exports = {
+  createLogger,
+};

package/lib/sessions.js

@@ -0,0 +1,125 @@
+const crypto = require("crypto");
+
+const SESSION_TTL_MS = 2 * 60 * 60 * 1000;
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+const MAX_SESSIONS = 10000;
+
+function createSession(sessionHash, nowMs) {
+  return {
+    session_hash: sessionHash,
+    created_at: nowMs,
+    last_seen_at: nowMs,
+    call_count: 0,
+    calls_in_current_window: 0,
+    window_start: nowMs,
+    history: [],
+    last_served_id: null,
+  };
+}
+
+function createSessionManager(config) {
+  const sessions = new Map();
+
+  const cleanupTimer = setInterval(() => {
+    const nowMs = Date.now();
+    for (const [key, session] of sessions.entries()) {
+      const lastSeen = session.last_seen_at || session.created_at;
+      if (nowMs - lastSeen > SESSION_TTL_MS) {
+        sessions.delete(key);
+      }
+    }
+  }, CLEANUP_INTERVAL_MS);
+
+  if (typeof cleanupTimer.unref === "function") {
+    cleanupTimer.unref();
+  }
+
+  function hashSessionId(sessionId) {
+    return crypto
+      .createHmac("sha256", config.logHashSecret)
+      .update(String(sessionId), "utf8")
+      .digest("hex");
+  }
+
+  function getSession(sessionHash) {
+    return sessions.get(sessionHash) || null;
+  }
+
+  function getOrCreateSession(sessionHash, nowMs = Date.now()) {
+    let session = sessions.get(sessionHash);
+    if (!session) {
+      if (sessions.size >= MAX_SESSIONS) {
+        return null;
+      }
+      session = createSession(sessionHash, nowMs);
+      sessions.set(sessionHash, session);
+    }
+    return session;
+  }
+
+  function evaluateRequest(session, nowMs = Date.now()) {
+    if (!session) {
+      return { allowed: true, reason: null };
+    }
+
+    session.last_seen_at = nowMs;
+
+    if (nowMs - session.window_start >= config.rateLimitWindowMs) {
+      session.window_start = nowMs;
+      session.calls_in_current_window = 0;
+    }
+
+    if (session.calls_in_current_window >= config.rateLimitMaxPerWindow) {
+      return { allowed: false, reason: "rate_limit" };
+    }
+
+    return { allowed: true, reason: null };
+  }
+
+  function recordDelivery(session, reflectionId, nowMs = Date.now()) {
+    if (!session) {
+      return null;
+    }
+
+    session.last_seen_at = nowMs;
+    session.call_count += 1;
+    session.calls_in_current_window += 1;
+    session.last_served_id = reflectionId;
+    session.history.push(reflectionId);
+
+    if (session.history.length > 100) {
+      session.history.shift();
+    }
+
+    return session.call_count;
+  }
+
+  function recordCall(session, nowMs = Date.now()) {
+    if (!session) {
+      return null;
+    }
+    session.last_seen_at = nowMs;
+    session.call_count += 1;
+    session.calls_in_current_window += 1;
+    return session.call_count;
+  }
+
+  function stop() {
+    clearInterval(cleanupTimer);
+  }
+
+  return {
+    hashSessionId,
+    getSession,
+    getOrCreateSession,
+    evaluateRequest,
+    recordDelivery,
+    recordCall,
+    stop,
+    getSessionCount: () => sessions.size,
+  };
+}
+
+module.exports = {
+  createSessionManager,
+};