@cubis/foundry 0.3.49 → 0.3.50

package/mcp/src/telemetry/tokenBudget.ts

@@ -67,6 +67,7 @@ export interface SkillToolMetrics {
   charsPerToken: number;
   fullCatalogEstimatedTokens: number;
   responseEstimatedTokens: number;
+  responseCharacterCount: number;
   selectedSkillsEstimatedTokens: number | null;
   loadedSkillEstimatedTokens: number | null;
   estimatedSavingsVsFullCatalog: number;
@@ -80,24 +81,30 @@ export function buildSkillToolMetrics({
   responseEstimatedTokens,
   selectedSkillsEstimatedTokens = null,
   loadedSkillEstimatedTokens = null,
+  responseCharacterCount = 0,
 }: {
   charsPerToken: number;
   fullCatalogEstimatedTokens: number;
   responseEstimatedTokens: number;
   selectedSkillsEstimatedTokens?: number | null;
   loadedSkillEstimatedTokens?: number | null;
+  responseCharacterCount?: number;
 }): SkillToolMetrics {
   const usedEstimatedTokens =
     loadedSkillEstimatedTokens ??
     selectedSkillsEstimatedTokens ??
     responseEstimatedTokens;
-  const savings = estimateSavings(fullCatalogEstimatedTokens, usedEstimatedTokens);
+  const savings = estimateSavings(
+    fullCatalogEstimatedTokens,
+    usedEstimatedTokens,
+  );
 
   return {
     estimatorVersion: TOKEN_ESTIMATOR_VERSION,
     charsPerToken: normalizeCharsPerToken(charsPerToken),
     fullCatalogEstimatedTokens: Math.max(0, fullCatalogEstimatedTokens),
     responseEstimatedTokens: Math.max(0, responseEstimatedTokens),
+    responseCharacterCount: Math.max(0, responseCharacterCount),
     selectedSkillsEstimatedTokens:
       selectedSkillsEstimatedTokens === null
         ? null
@@ -111,4 +118,3 @@ export function buildSkillToolMetrics({
     estimated: true,
   };
 }
-

package/mcp/src/tools/skillBrowseCategory.ts

@@ -47,7 +47,8 @@ export async function handleSkillBrowseCategory(
   const payload = { category, skills, count: skills.length };
   const text = JSON.stringify(payload, null, 2);
   const selectedSkillsEstimatedTokens = matching.reduce(
-    (sum, skill) => sum + estimateTokensFromBytes(skill.fileBytes, charsPerToken),
+    (sum, skill) =>
+      sum + estimateTokensFromBytes(skill.fileBytes, charsPerToken),
     0,
   );
   const metrics = buildSkillToolMetrics({
@@ -55,6 +56,7 @@ export async function handleSkillBrowseCategory(
     fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
     responseEstimatedTokens: estimateTokensFromText(text, charsPerToken),
     selectedSkillsEstimatedTokens,
+    responseCharacterCount: text.length,
   });
 
   return {
@@ -67,5 +69,8 @@ export async function handleSkillBrowseCategory(
     structuredContent: {
       metrics,
     },
+    _meta: {
+      metrics,
+    },
   };
 }

package/mcp/src/tools/skillBudgetReport.ts

@@ -49,7 +49,10 @@ export function handleSkillBudgetReport(
       return {
         id: skill.id,
         category: skill.category,
-        estimatedTokens: estimateTokensFromBytes(skill.fileBytes, charsPerToken),
+        estimatedTokens: estimateTokensFromBytes(
+          skill.fileBytes,
+          charsPerToken,
+        ),
       };
     })
     .filter((item): item is NonNullable<typeof item> => Boolean(item));
@@ -61,7 +64,10 @@ export function handleSkillBudgetReport(
       return {
         id: skill.id,
         category: skill.category,
-        estimatedTokens: estimateTokensFromBytes(skill.fileBytes, charsPerToken),
+        estimatedTokens: estimateTokensFromBytes(
+          skill.fileBytes,
+          charsPerToken,
+        ),
       };
     })
     .filter((item): item is NonNullable<typeof item> => Boolean(item));
@@ -69,7 +75,9 @@ export function handleSkillBudgetReport(
   const unknownSelectedSkillIds = selectedSkillIds.filter(
     (id) => !skillById.has(id),
   );
-  const unknownLoadedSkillIds = loadedSkillIds.filter((id) => !skillById.has(id));
+  const unknownLoadedSkillIds = loadedSkillIds.filter(
+    (id) => !skillById.has(id),
+  );
 
   const selectedSkillsEstimatedTokens = selectedSkills.reduce(
     (sum, skill) => sum + skill.estimatedTokens,
@@ -92,7 +100,9 @@ export function handleSkillBudgetReport(
   const selectedIdSet = new Set(selectedSkills.map((skill) => skill.id));
   const loadedIdSet = new Set(loadedSkills.map((skill) => skill.id));
   const skippedSkills = manifest.skills
-    .filter((skill) => !selectedIdSet.has(skill.id) && !loadedIdSet.has(skill.id))
+    .filter(
+      (skill) => !selectedIdSet.has(skill.id) && !loadedIdSet.has(skill.id),
+    )
     .map((skill) => skill.id)
     .sort((a, b) => a.localeCompare(b));
 
@@ -116,13 +126,16 @@ export function handleSkillBudgetReport(
     },
   };
 
+  const text = JSON.stringify(payload, null, 2);
+
   return {
     content: [
       {
         type: "text" as const,
-        text: JSON.stringify(payload, null, 2),
+        text,
       },
     ],
     structuredContent: payload,
+    _meta: payload,
   };
 }

package/mcp/src/tools/skillGet.ts

@@ -66,6 +66,13 @@ export async function handleSkillGet(
         ].join("\n")
       : "";
   const content = `${skillContent}${referenceSection}`;
+
+  if (content.trim().length === 0) {
+    invalidInput(
+      `Skill "${id}" has empty content (SKILL.md is empty or whitespace-only). This skill may be corrupt or incomplete.`,
+    );
+  }
+
   const loadedSkillEstimatedTokens = estimateTokensFromText(
     content,
     charsPerToken,
@@ -75,6 +82,7 @@ export async function handleSkillGet(
     fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
     responseEstimatedTokens: loadedSkillEstimatedTokens,
     loadedSkillEstimatedTokens,
+    responseCharacterCount: content.length,
   });
 
   return {
@@ -88,5 +96,9 @@ export async function handleSkillGet(
       references: references.map((ref) => ({ path: ref.relativePath })),
       metrics,
     },
+    _meta: {
+      references: references.map((ref) => ({ path: ref.relativePath })),
+      metrics,
+    },
   };
 }

package/mcp/src/tools/skillListCategories.ts

@@ -37,6 +37,7 @@ export function handleSkillListCategories(
     charsPerToken,
     fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
     responseEstimatedTokens: estimateTokensFromText(text, charsPerToken),
+    responseCharacterCount: text.length,
   });
 
   return {
@@ -49,5 +50,8 @@ export function handleSkillListCategories(
     structuredContent: {
       metrics,
     },
+    _meta: {
+      metrics,
+    },
   };
 }

package/mcp/src/tools/skillSearch.ts

@@ -65,7 +65,8 @@ export async function handleSkillSearch(
   const payload = { query, results, count: results.length };
   const text = JSON.stringify(payload, null, 2);
   const selectedSkillsEstimatedTokens = matches.reduce(
-    (sum, skill) => sum + estimateTokensFromBytes(skill.fileBytes, charsPerToken),
+    (sum, skill) =>
+      sum + estimateTokensFromBytes(skill.fileBytes, charsPerToken),
     0,
   );
   const metrics = buildSkillToolMetrics({
@@ -73,6 +74,7 @@ export async function handleSkillSearch(
     fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
     responseEstimatedTokens: estimateTokensFromText(text, charsPerToken),
     selectedSkillsEstimatedTokens,
+    responseCharacterCount: text.length,
   });
 
   return {
@@ -85,5 +87,8 @@ export async function handleSkillSearch(
     structuredContent: {
       metrics,
     },
+    _meta: {
+      metrics,
+    },
   };
 }

package/mcp/src/transports/streamableHttp.ts

@@ -1,19 +1,263 @@
 /**
  * Cubis Foundry MCP Server – Streamable HTTP transport adapter.
  *
- * Uses the SDK's StreamableHTTPServerTransport for remote connections.
- * Binds to localhost by default (security: prevents DNS rebinding).
+ * Multi-session architecture: each initialize handshake creates a new
+ * StreamableHTTPServerTransport + McpServer pair. Subsequent requests with
+ * the returned `mcp-session-id` header are routed to the correct session.
+ * This eliminates the "Server already initialized" error when smoke tests
+ * or multiple clients hit the same container without restarting.
+ *
+ * Idle sessions are cleaned up after SESSION_TTL_MS (30 min default).
  */
 
-import { createServer, type Server } from "node:http";
+import {
+  createServer,
+  type Server,
+  type IncomingMessage,
+  type ServerResponse,
+} from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { logger } from "../utils/logger.js";
 
+/** Default session idle TTL in ms (30 minutes). */
+const SESSION_TTL_MS = 30 * 60 * 1000;
+
+/** Cleanup sweep interval in ms (5 minutes). */
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+
 export interface HttpTransportOptions {
   port: number;
   host: string;
 }
 
+/**
+ * Callback invoked to create a new McpServer, register tools, and connect
+ * it to the provided transport. Called once per session.
+ */
+export type McpServerFactory = (
+  transport: StreamableHTTPServerTransport,
+) => Promise<McpServer>;
+
+interface SessionEntry {
+  transport: StreamableHTTPServerTransport;
+  server: McpServer;
+  lastActivity: number;
+}
+
+export interface MultiSessionHttpServer {
+  httpServer: Server;
+  /** Gracefully close all sessions and the HTTP server. */
+  closeAll(): Promise<void>;
+}
+
+/**
+ * Read the raw body from an IncomingMessage so we can inspect it before
+ * handing it to the SDK transport.
+ */
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (c: Buffer) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+export function createMultiSessionHttpServer(
+  options: HttpTransportOptions,
+  serverFactory: McpServerFactory,
+): MultiSessionHttpServer {
+  const sessions = new Map<string, SessionEntry>();
+
+  // ── Periodic cleanup of idle sessions ───────────────────
+  const cleanupTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [id, entry] of sessions) {
+      if (now - entry.lastActivity > SESSION_TTL_MS) {
+        logger.info(
+          `Session ${id.slice(0, 8)} expired after idle (active: ${sessions.size - 1})`,
+        );
+        entry.transport.close().catch(() => {});
+        entry.server.close().catch(() => {});
+        sessions.delete(id);
+      }
+    }
+  }, CLEANUP_INTERVAL_MS);
+  cleanupTimer.unref(); // Don't prevent process exit
+
+  // ── HTTP request handler ────────────────────────────────
+  const httpServer = createServer(
+    async (req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+      if (url.pathname !== "/mcp") {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found");
+        return;
+      }
+
+      // DELETE = session termination (per MCP spec)
+      if (req.method === "DELETE") {
+        const sid = req.headers["mcp-session-id"] as string | undefined;
+        if (sid && sessions.has(sid)) {
+          const entry = sessions.get(sid)!;
+          await entry.transport.close().catch(() => {});
+          await entry.server.close().catch(() => {});
+          sessions.delete(sid);
+          logger.info(
+            `Session ${sid.slice(0, 8)} terminated (active: ${sessions.size})`,
+          );
+          res.writeHead(200, { "Content-Type": "text/plain" });
+          res.end("Session closed");
+        } else {
+          res.writeHead(404, { "Content-Type": "text/plain" });
+          res.end("Session not found");
+        }
+        return;
+      }
+
+      // GET = SSE stream for an existing session
+      if (req.method === "GET") {
+        const sid = req.headers["mcp-session-id"] as string | undefined;
+        if (sid && sessions.has(sid)) {
+          const entry = sessions.get(sid)!;
+          entry.lastActivity = Date.now();
+          await entry.transport.handleRequest(req, res);
+        } else {
+          res.writeHead(400, { "Content-Type": "text/plain" });
+          res.end("Missing or invalid mcp-session-id");
+        }
+        return;
+      }
+
+      // POST = either initialize (new session) or call (existing session)
+      if (req.method === "POST") {
+        const sid = req.headers["mcp-session-id"] as string | undefined;
+
+        // Existing session — route to its transport
+        if (sid && sessions.has(sid)) {
+          const entry = sessions.get(sid)!;
+          entry.lastActivity = Date.now();
+          await entry.transport.handleRequest(req, res);
+          return;
+        }
+
+        // Peek at the body to determine if this is an initialize request
+        const rawBody = await readBody(req);
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(rawBody);
+        } catch {
+          logger.warn(`Bad JSON in POST from ${req.socket.remoteAddress}`);
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(
+            JSON.stringify({
+              jsonrpc: "2.0",
+              error: { code: -32700, message: "Parse error" },
+              id: null,
+            }),
+          );
+          return;
+        }
+
+        const isInit =
+          parsed &&
+          typeof parsed === "object" &&
+          "method" in parsed &&
+          (parsed as Record<string, unknown>).method === "initialize";
+
+        if (!isInit) {
+          // Non-init request without valid session
+          logger.warn(
+            `POST without session: method=${(parsed as Record<string, unknown>)?.method ?? "unknown"}`,
+          );
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(
+            JSON.stringify({
+              jsonrpc: "2.0",
+              error: {
+                code: -32600,
+                message: "Invalid Request: missing or unknown mcp-session-id",
+              },
+              id: (parsed as Record<string, unknown>)?.id ?? null,
+            }),
+          );
+          return;
+        }
+
+        // ── New session: create transport + server ──────────
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => crypto.randomUUID(),
+        });
+
+        try {
+          const server = await serverFactory(transport);
+
+          // Re-inject the pre-read body so the transport can process it.
+          // The SDK's StreamableHTTPServerTransport accepts a parsedBody
+          // parameter to avoid re-reading the stream.
+          await transport.handleRequest(req, res, parsed);
+
+          // After handleRequest, the transport.sessionId is set by the SDK.
+          const sessionId = transport.sessionId;
+          if (sessionId) {
+            sessions.set(sessionId, {
+              transport,
+              server,
+              lastActivity: Date.now(),
+            });
+            logger.info(
+              `New session ${sessionId.slice(0, 8)} (active: ${sessions.size})`,
+            );
+          }
+        } catch (error) {
+          logger.error(`Failed to create MCP session: ${error}`);
+          if (!res.headersSent) {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(
+              JSON.stringify({
+                jsonrpc: "2.0",
+                error: {
+                  code: -32603,
+                  message: "Internal error creating session",
+                },
+                id: (parsed as Record<string, unknown>)?.id ?? null,
+              }),
+            );
+          }
+        }
+        return;
+      }
+
+      // Unsupported method
+      res.writeHead(405, { "Content-Type": "text/plain" });
+      res.end("Method Not Allowed");
+    },
+  );
+
+  httpServer.listen(options.port, options.host, () => {
+    logger.info(
+      `Streamable HTTP transport listening on http://${options.host}:${options.port}/mcp (multi-session)`,
+    );
+  });
+
+  async function closeAll(): Promise<void> {
+    clearInterval(cleanupTimer);
+    for (const [id, entry] of sessions) {
+      await entry.transport.close().catch(() => {});
+      await entry.server.close().catch(() => {});
+      sessions.delete(id);
+      logger.debug(`Closed session ${id} during shutdown`);
+    }
+    httpServer.close();
+  }
+
+  return { httpServer, closeAll };
+}
+
+// ── Legacy single-session export (kept for backward compat) ──
+
+/** @deprecated Use createMultiSessionHttpServer instead. */
 export function createStreamableHttpTransport(options: HttpTransportOptions): {
   transport: StreamableHTTPServerTransport;
   httpServer: Server;
@@ -23,7 +267,6 @@ export function createStreamableHttpTransport(options: HttpTransportOptions): {
   });
 
   const httpServer = createServer(async (req, res) => {
-    // Only handle the /mcp endpoint
     const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
     if (url.pathname !== "/mcp") {
       res.writeHead(404, { "Content-Type": "text/plain" });

package/mcp/src/utils/logger.ts

@@ -13,7 +13,11 @@ const LEVEL_ORDER: Record<LogLevel, number> = {
   error: 3,
 };
 
-let currentLevel: LogLevel = "info";
+let currentLevel: LogLevel =
+  (process.env.LOG_LEVEL?.toLowerCase() as LogLevel) || "info";
+if (!LEVEL_ORDER[currentLevel]) {
+  currentLevel = "info";
+}
 
 export function setLogLevel(level: LogLevel): void {
   currentLevel = level;

package/mcp/src/vault/manifest.ts

@@ -182,18 +182,35 @@ async function readReferencedMarkdownFiles(
   return references;
 }
 
-async function collectSiblingMarkdownTargets(skillDir: string): Promise<string[]> {
+async function collectSiblingMarkdownTargets(
+  skillDir: string,
+): Promise<string[]> {
   const entries = await readdir(skillDir, { withFileTypes: true }).catch(
     () => [],
   );
   const targets: string[] = [];
 
   for (const entry of entries) {
-    if (!entry.isFile()) continue;
     if (entry.name.startsWith(".")) continue;
-    if (!entry.name.toLowerCase().endsWith(".md")) continue;
-    if (entry.name.toLowerCase() === "skill.md") continue;
-    targets.push(entry.name);
+
+    if (entry.isDirectory()) {
+      // One level deep: scan subdirectories like references/, steering/, parts/
+      const subEntries = await readdir(path.join(skillDir, entry.name), {
+        withFileTypes: true,
+      }).catch(() => []);
+      for (const sub of subEntries) {
+        if (!sub.isFile()) continue;
+        if (sub.name.startsWith(".")) continue;
+        if (!sub.name.toLowerCase().endsWith(".md")) continue;
+        targets.push(`${entry.name}/${sub.name}`);
+        if (targets.length >= MAX_REFERENCED_FILES) break;
+      }
+    } else if (entry.isFile()) {
+      if (!entry.name.toLowerCase().endsWith(".md")) continue;
+      if (entry.name.toLowerCase() === "skill.md") continue;
+      targets.push(entry.name);
+    }
+
     if (targets.length >= MAX_REFERENCED_FILES) break;
   }
 

package/mcp/src/vault/scanner.ts

@@ -40,6 +40,12 @@ export async function scanVaultRoots(
       const skillStat = await stat(skillFile).catch(() => null);
       if (!skillStat?.isFile()) continue;
 
+      // Skip empty SKILL.md files — they provide no instructions
+      if (skillStat.size === 0) {
+        logger.warn(`Skipping empty SKILL.md: ${skillFile}`);
+        continue;
+      }
+
       const wrapperKind = await detectWrapperKind(entry, skillFile);
       if (wrapperKind) {
         logger.debug(
@@ -67,14 +73,18 @@ const WRAPPER_PREFIXES = ["workflow-", "agent-"] as const;
 const WRAPPER_KINDS = new Set(["workflow", "agent"]);
 const FRONTMATTER_PREVIEW_BYTES = 8192;
 
-function extractWrapperKindFromId(skillId: string): "workflow" | "agent" | null {
+function extractWrapperKindFromId(
+  skillId: string,
+): "workflow" | "agent" | null {
   const lower = skillId.toLowerCase();
   if (lower.startsWith(WRAPPER_PREFIXES[0])) return "workflow";
   if (lower.startsWith(WRAPPER_PREFIXES[1])) return "agent";
   return null;
 }
 
-async function readFrontmatterPreview(skillFile: string): Promise<string | null> {
+async function readFrontmatterPreview(
+  skillFile: string,
+): Promise<string | null> {
   const handle = await open(skillFile, "r").catch(() => null);
   if (!handle) return null;
 
@@ -116,7 +126,10 @@ function extractMetadataWrapper(frontmatter: string): string | null {
     const match = line.match(/^\s+wrapper\s*:\s*(.+)\s*$/);
     if (!match) continue;
 
-    const value = match[1].trim().replace(/^['"]|['"]$/g, "").toLowerCase();
+    const value = match[1]
+      .trim()
+      .replace(/^['"]|['"]$/g, "")
+      .toLowerCase();
     if (WRAPPER_KINDS.has(value)) {
       return value;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubis/foundry",
-  "version": "0.3.49",
+  "version": "0.3.50",
   "description": "Cubis Foundry CLI for workflow-first AI agent environments",
   "type": "module",
   "bin": {