@cubis/foundry 0.3.40 → 0.3.42

package/mcp/src/tools/skillSearch.ts

@@ -8,6 +8,11 @@
 import { z } from "zod";
 import type { VaultManifest } from "../vault/types.js";
 import { enrichWithDescriptions } from "../vault/manifest.js";
+import {
+  buildSkillToolMetrics,
+  estimateTokensFromBytes,
+  estimateTokensFromText,
+} from "../telemetry/tokenBudget.js";
 
 export const skillSearchName = "skill_search";
 
@@ -27,6 +32,7 @@ export async function handleSkillSearch(
   args: z.infer<typeof skillSearchSchema>,
   manifest: VaultManifest,
   summaryMaxLength: number,
+  charsPerToken: number,
 ) {
   const { query } = args;
   const lower = query.toLowerCase();
@@ -56,17 +62,28 @@ export async function handleSkillSearch(
     category: s.category,
     description: s.description ?? "(no description)",
   }));
+  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),
+    0,
+  );
+  const metrics = buildSkillToolMetrics({
+    charsPerToken,
+    fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+    responseEstimatedTokens: estimateTokensFromText(text, charsPerToken),
+    selectedSkillsEstimatedTokens,
+  });
 
   return {
     content: [
       {
         type: "text" as const,
-        text: JSON.stringify(
-          { query, results, count: results.length },
-          null,
-          2,
-        ),
+        text,
       },
     ],
+    structuredContent: {
+      metrics,
+    },
   };
 }

package/mcp/src/tools/skillTools.test.ts

@@ -1,9 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtempSync, statSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { VaultManifest } from "../vault/types.js";
 import { handleSkillBrowseCategory } from "./skillBrowseCategory.js";
+import { handleSkillBudgetReport } from "./skillBudgetReport.js";
 import { handleSkillGet } from "./skillGet.js";
 import { handleSkillListCategories } from "./skillListCategories.js";
 import { handleSkillSearch } from "./skillSearch.js";
@@ -12,6 +13,10 @@ function payload(result: { content: Array<{ text: string }> }): Record<string, u
   return JSON.parse(result.content[0].text) as Record<string, unknown>;
 }
 
+function metrics(result: { structuredContent?: Record<string, unknown> }): Record<string, unknown> {
+  return (result.structuredContent?.metrics || {}) as Record<string, unknown>;
+}
+
 function createSkillFile(id: string, description: string, body = "# Content"): string {
   const dir = mkdtempSync(path.join(os.tmpdir(), `mcp-skill-${id}-`));
   const file = path.join(dir, "SKILL.md");
@@ -32,27 +37,47 @@ function createManifest(): VaultManifest {
     "fastapi-expert",
     "FastAPI async backend patterns",
   );
+  const reactBytes = statSync(reactFile).size;
+  const fastapiBytes = statSync(fastapiFile).size;
+  const fullCatalogBytes = reactBytes + fastapiBytes;
 
   return {
     categories: ["backend", "frontend"],
     skills: [
-      { id: "react-expert", category: "frontend", path: reactFile },
-      { id: "fastapi-expert", category: "backend", path: fastapiFile },
+      {
+        id: "react-expert",
+        category: "frontend",
+        path: reactFile,
+        fileBytes: reactBytes,
+      },
+      {
+        id: "fastapi-expert",
+        category: "backend",
+        path: fastapiFile,
+        fileBytes: fastapiBytes,
+      },
     ],
+    fullCatalogBytes,
+    fullCatalogEstimatedTokens: Math.ceil(fullCatalogBytes / 4),
   };
 }
 
 describe("skill tools", () => {
   it("lists categories with skill counts", () => {
     const manifest = createManifest();
-    const result = handleSkillListCategories(manifest);
+    const result = handleSkillListCategories(manifest, 4);
     const data = payload(result);
+    const toolMetrics = metrics(result);
 
     expect(data.totalSkills).toBe(2);
     expect(data.categories).toEqual([
       { category: "backend", skillCount: 1 },
       { category: "frontend", skillCount: 1 },
     ]);
+    expect(toolMetrics.estimatorVersion).toBeDefined();
+    expect(toolMetrics.fullCatalogEstimatedTokens).toBe(
+      manifest.fullCatalogEstimatedTokens,
+    );
   });
 
   it("browses a category with enriched descriptions", async () => {
@@ -61,8 +86,10 @@ describe("skill tools", () => {
       { category: "frontend" },
       manifest,
       200,
+      4,
     );
     const data = payload(result);
+    const toolMetrics = metrics(result);
 
     expect(data.category).toBe("frontend");
     expect(data.count).toBe(1);
@@ -72,12 +99,13 @@ describe("skill tools", () => {
         description: "React performance and architecture guidance",
       },
     ]);
+    expect(toolMetrics.selectedSkillsEstimatedTokens).toBeGreaterThan(0);
   });
 
   it("throws when browsing an unknown category", async () => {
     const manifest = createManifest();
     await expect(
-      handleSkillBrowseCategory({ category: "mobile" }, manifest, 200),
+      handleSkillBrowseCategory({ category: "mobile" }, manifest, 200, 4),
     ).rejects.toThrow('Category not found: "mobile"');
   });
 
@@ -85,7 +113,7 @@ describe("skill tools", () => {
     const manifest = createManifest();
 
     const byId = payload(
-      await handleSkillSearch({ query: "react" }, manifest, 200),
+      await handleSkillSearch({ query: "react" }, manifest, 200, 4),
     );
     expect(byId.count).toBe(1);
     expect(byId.results).toEqual([
@@ -97,7 +125,7 @@ describe("skill tools", () => {
     ]);
 
     const byDescription = payload(
-      await handleSkillSearch({ query: "async backend" }, manifest, 200),
+      await handleSkillSearch({ query: "async backend" }, manifest, 200, 4),
     );
     expect(byDescription.count).toBe(1);
     expect(byDescription.results).toEqual([
@@ -111,16 +139,40 @@ describe("skill tools", () => {
 
   it("returns full skill content for skill_get", async () => {
     const manifest = createManifest();
-    const result = await handleSkillGet({ id: "react-expert" }, manifest);
+    const result = await handleSkillGet({ id: "react-expert" }, manifest, 4);
+    const toolMetrics = metrics(result);
 
     expect(result.content[0].text).toContain("# Content");
     expect(result.content[0].text).toContain("description: React performance");
+    expect(toolMetrics.loadedSkillEstimatedTokens).toBeGreaterThan(0);
   });
 
   it("throws when skill_get cannot find the requested skill", async () => {
     const manifest = createManifest();
-    await expect(handleSkillGet({ id: "missing" }, manifest)).rejects.toThrow(
+    await expect(handleSkillGet({ id: "missing" }, manifest, 4)).rejects.toThrow(
       'Skill not found: "missing"',
     );
   });
+
+  it("returns consolidated budget rollup for selected and loaded skills", () => {
+    const manifest = createManifest();
+    const result = handleSkillBudgetReport(
+      {
+        selectedSkillIds: ["react-expert", "missing-skill"],
+        loadedSkillIds: ["react-expert"],
+      },
+      manifest,
+      4,
+    );
+    const data = payload(result);
+
+    expect(data.skillLog).toBeDefined();
+    expect(data.contextBudget).toMatchObject({
+      fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+      estimated: true,
+    });
+    expect(
+      (data.skillLog as Record<string, unknown>).unknownSelectedSkillIds,
+    ).toContain("missing-skill");
+  });
 });

package/mcp/src/vault/manifest.test.ts

@@ -3,6 +3,7 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import {
+  buildManifest,
   enrichWithDescriptions,
   extractDescription,
   parseDescriptionFromFrontmatter,
@@ -109,11 +110,12 @@ describe("manifest enrichment", () => {
 
     const enriched = await enrichWithDescriptions(
       [
-        { id: "alpha", category: "general", path: fileA },
+        { id: "alpha", category: "general", path: fileA, fileBytes: 64 },
         {
           id: "beta",
           category: "general",
           path: fileB,
+          fileBytes: 64,
           description: "Already populated",
         },
       ],
@@ -124,3 +126,19 @@ describe("manifest enrichment", () => {
     expect(enriched[1].description).toBe("Already populated");
   });
 });
+
+describe("buildManifest", () => {
+  it("computes full catalog byte and token totals", () => {
+    const manifest = buildManifest(
+      [
+        { id: "a", category: "general", path: "/tmp/a.md", fileBytes: 20 },
+        { id: "b", category: "frontend", path: "/tmp/b.md", fileBytes: 12 },
+      ],
+      4,
+    );
+
+    expect(manifest.categories).toEqual(["frontend", "general"]);
+    expect(manifest.fullCatalogBytes).toBe(32);
+    expect(manifest.fullCatalogEstimatedTokens).toBe(8);
+  });
+});

package/mcp/src/vault/manifest.ts

@@ -8,19 +8,30 @@
 import { readFile } from "node:fs/promises";
 import type { SkillPointer, VaultManifest } from "./types.js";
 import { logger } from "../utils/logger.js";
+import { estimateTokensFromBytes } from "../telemetry/tokenBudget.js";
 
 /**
  * Build a VaultManifest from scanned skill pointers.
  * Categories are derived from the pointers.
  */
-export function buildManifest(skills: SkillPointer[]): VaultManifest {
+export function buildManifest(
+  skills: SkillPointer[],
+  charsPerToken: number,
+): VaultManifest {
   const categorySet = new Set<string>();
+  let fullCatalogBytes = 0;
   for (const skill of skills) {
     categorySet.add(skill.category);
+    fullCatalogBytes += skill.fileBytes;
   }
   return {
     categories: [...categorySet].sort(),
     skills,
+    fullCatalogBytes,
+    fullCatalogEstimatedTokens: estimateTokensFromBytes(
+      fullCatalogBytes,
+      charsPerToken,
+    ),
   };
 }
 

package/mcp/src/vault/scanner.test.ts

@@ -52,6 +52,7 @@ describe("scanVaultRoots", () => {
     expect(byId["react-expert"]).toBe("frontend");
     expect(byId["database-design"]).toBe("data");
     expect(byId["custom-skill"]).toBe("general");
+    expect(skills.every((skill) => skill.fileBytes > 0)).toBe(true);
   });
 
   it("skips missing roots and continues scanning valid roots", async () => {

package/mcp/src/vault/scanner.ts

@@ -46,6 +46,7 @@ export async function scanVaultRoots(
         id: entry,
         category: deriveCategory(entry),
         path: skillFile,
+        fileBytes: skillStat.size,
       });
     }
   }

package/mcp/src/vault/types.ts

@@ -9,6 +9,8 @@ export interface SkillPointer {
   category: string;
   /** Absolute path to the SKILL.md file. */
   path: string;
+  /** Skill file size in bytes. */
+  fileBytes: number;
   /** Short description extracted from frontmatter (truncated). */
   description?: string;
 }
@@ -18,4 +20,8 @@ export interface VaultManifest {
   categories: string[];
   /** All skill pointers (metadata only – no full content). */
   skills: SkillPointer[];
+  /** Total bytes across all discovered SKILL.md files. */
+  fullCatalogBytes: number;
+  /** Estimated full-catalog token usage (deterministic estimator). */
+  fullCatalogEstimatedTokens: number;
 }

package/package.json

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

package/workflows/workflows/agent-environment-setup/platforms/antigravity/rules/GEMINI.md

@@ -68,6 +68,32 @@ Use the best specialist first:
 
 ## 5) Skill Loading Policy
 
+## MCP-first Skill Discovery Order (Required)
+
+1. Use `skill_search` first to narrow candidate skills.
+2. Use `skill_browse_category` second to inspect category-level candidates.
+3. Use `skill_get` only for final selected skills that must be loaded.
+4. Keep pointer-first flow; avoid loading full skill text prematurely.
+
+## Skill Log Completion Block (Required)
+
+After finishing skill selection/loading, publish:
+
+- `selected_skills`: skill IDs selected for the task
+- `loaded_skills`: skill IDs loaded via `skill_get`
+- `skipped_skills`: considered but not loaded
+
+## Context Budget Block (Required, Estimated)
+
+Immediately after the Skill Log block, publish estimated budget fields:
+
+- `full_catalog_est_tokens`
+- `loaded_est_tokens`
+- `estimated_savings_tokens`
+- `estimated_savings_percent`
+
+Mark all context/token values as deterministic estimates (not provider metering).
+
 ### Smart Skill Selection (Adaptive)
 
 Use an adaptive load policy to control context size:
@@ -85,6 +111,8 @@ Use an adaptive load policy to control context size:
 4.  If a mapped skill is missing, continue with best fallback and state it.
 5.  Keep user-visible decision logs concise: selected skill(s) and one-line rationale.
 
+After the skill log is complete, append the Context Budget block in the same response/update.
+
 ## 6) Socratic Gate (Before Complex Work)
 
 Before multi-file or architecture-impacting changes, ask targeted questions when requirements are unclear:

package/workflows/workflows/agent-environment-setup/platforms/codex/rules/AGENTS.md

@@ -14,12 +14,13 @@ This file defines mandatory behavior for Codex projects installed via `cbx workf
 Before executing workflows, agents, or code edits, publish a short `Decision Log` that is visible to the user:
 
 1. Rule file(s) read at startup (at minimum `AGENTS.md`, plus any additional rule files loaded).
-2. Workflow decision (`$workflow-*` or direct mode) and why it was chosen.
-3. Agent routing decision (`$agent-*` or direct mode) and why it was chosen.
+2. Workflow decision ($workflow-* or direct mode) and why it was chosen.
+3. Agent routing decision ($agent-* or direct mode) and why it was chosen.
 4. Skill loading decision (skill names loaded) and why they were chosen.
 
 If routing changes during the task, publish a `Decision Update` before continuing.
 Keep this user-visible summary concise and factual; do not expose private chain-of-thought.
+When mentioning wrappers in user-visible logs, use raw $workflow-* and $agent-* tokens (no backticks) so Codex can render icon/blue mention styling.
 
 ## 2) Skill-Based Workflow
 
@@ -63,6 +64,32 @@ Use the best specialist first:
 
 ## 5) Skill Loading Policy
 
+## MCP-first Skill Discovery Order (Required)
+
+1. Use `skill_search` first to narrow candidate skills.
+2. Use `skill_browse_category` second to inspect category-level candidates.
+3. Use `skill_get` only for final selected skills that must be loaded.
+4. Keep pointer-first flow; avoid loading full skill text prematurely.
+
+## Skill Log Completion Block (Required)
+
+After finishing skill selection/loading, publish:
+
+- `selected_skills`: skill IDs selected for the task
+- `loaded_skills`: skill IDs loaded via `skill_get`
+- `skipped_skills`: considered but not loaded
+
+## Context Budget Block (Required, Estimated)
+
+Immediately after the Skill Log block, publish estimated budget fields:
+
+- `full_catalog_est_tokens`
+- `loaded_est_tokens`
+- `estimated_savings_tokens`
+- `estimated_savings_percent`
+
+Mark all context/token values as deterministic estimates (not provider metering).
+
 ### Smart Skill Selection (Adaptive)
 
 Use an adaptive load policy to control context size:
@@ -80,6 +107,8 @@ Use an adaptive load policy to control context size:
 4.  If a mapped skill is missing, continue with best fallback and state it.
 5.  Keep user-visible decision logs concise: selected skill(s) and one-line rationale.
 
+After the skill log is complete, append the Context Budget block in the same response/update.
+
 ## 6) Socratic Gate (Before Complex Work)
 
 Before multi-file or architecture-impacting changes, ask targeted questions when requirements are unclear:

package/workflows/workflows/agent-environment-setup/platforms/copilot/rules/AGENTS.md

@@ -72,6 +72,32 @@ When authoring custom Copilot assets, keep frontmatter schema compatible:
 
 ## 6) Skill Loading Policy
 
+## MCP-first Skill Discovery Order (Required)
+
+1. Use `skill_search` first to narrow candidate skills.
+2. Use `skill_browse_category` second to inspect category-level candidates.
+3. Use `skill_get` only for final selected skills that must be loaded.
+4. Keep pointer-first flow; avoid loading full skill text prematurely.
+
+## Skill Log Completion Block (Required)
+
+After finishing skill selection/loading, publish:
+
+- `selected_skills`: skill IDs selected for the task
+- `loaded_skills`: skill IDs loaded via `skill_get`
+- `skipped_skills`: considered but not loaded
+
+## Context Budget Block (Required, Estimated)
+
+Immediately after the Skill Log block, publish estimated budget fields:
+
+- `full_catalog_est_tokens`
+- `loaded_est_tokens`
+- `estimated_savings_tokens`
+- `estimated_savings_percent`
+
+Mark all context/token values as deterministic estimates (not provider metering).
+
 ### Smart Skill Selection (Adaptive)
 
 Use an adaptive load policy to control context size:
@@ -89,6 +115,8 @@ Use an adaptive load policy to control context size:
 4.  If a mapped skill is missing, continue with best fallback and state it.
 5.  Keep user-visible decision logs concise: selected skill(s) and one-line rationale.
 
+After the skill log is complete, append the Context Budget block in the same response/update.
+
 ## 7) Socratic Gate (Before Complex Work)
 
 Before multi-file or architecture-impacting changes, ask targeted questions when requirements are unclear:

package/workflows/workflows/agent-environment-setup/platforms/copilot/rules/copilot-instructions.md

@@ -72,6 +72,32 @@ When authoring custom Copilot assets, keep frontmatter schema compatible:
 
 ## 6) Skill Loading Policy
 
+## MCP-first Skill Discovery Order (Required)
+
+1. Use `skill_search` first to narrow candidate skills.
+2. Use `skill_browse_category` second to inspect category-level candidates.
+3. Use `skill_get` only for final selected skills that must be loaded.
+4. Keep pointer-first flow; avoid loading full skill text prematurely.
+
+## Skill Log Completion Block (Required)
+
+After finishing skill selection/loading, publish:
+
+- `selected_skills`: skill IDs selected for the task
+- `loaded_skills`: skill IDs loaded via `skill_get`
+- `skipped_skills`: considered but not loaded
+
+## Context Budget Block (Required, Estimated)
+
+Immediately after the Skill Log block, publish estimated budget fields:
+
+- `full_catalog_est_tokens`
+- `loaded_est_tokens`
+- `estimated_savings_tokens`
+- `estimated_savings_percent`
+
+Mark all context/token values as deterministic estimates (not provider metering).
+
 ### Smart Skill Selection (TIER 0)
 
 Before starting ANY task, the agent MUST:
@@ -88,6 +114,8 @@ Before starting ANY task, the agent MUST:
 3.  Keep context lean; avoid loading unrelated skill documents.
 4.  If a mapped skill is missing, continue with best fallback and state it.
 
+After the skill log is complete, append the Context Budget block in the same response/update.
+
 ## 7) Socratic Gate (Before Complex Work)
 
 Before multi-file or architecture-impacting changes, ask targeted questions when requirements are unclear:

package/workflows/workflows/agent-environment-setup/platforms/cursor/rules/.cursorrules

@@ -32,11 +32,39 @@ Before starting ANY task, the agent MUST:
 
 ## 3) Skill Loading Policy
 
+## MCP-first Skill Discovery Order (Required)
+
+1. Use `skill_search` first to narrow candidate skills.
+2. Use `skill_browse_category` second to inspect category-level candidates.
+3. Use `skill_get` only for final selected skills that must be loaded.
+4. Keep pointer-first flow; avoid loading full skill text prematurely.
+
+## Skill Log Completion Block (Required)
+
+After finishing skill selection/loading, publish:
+
+- `selected_skills`: skill IDs selected for the task
+- `loaded_skills`: skill IDs loaded via `skill_get`
+- `skipped_skills`: considered but not loaded
+
+## Context Budget Block (Required, Estimated)
+
+Immediately after the Skill Log block, publish estimated budget fields:
+
+- `full_catalog_est_tokens`
+- `loaded_est_tokens`
+- `estimated_savings_tokens`
+- `estimated_savings_percent`
+
+Mark all context/token values as deterministic estimates (not provider metering).
+
 1.  Load only skills needed for the active request.
 2.  Prefer progressive disclosure: start from `SKILL.md`, then specific sections.
 3.  Keep context lean; avoid loading unrelated skill documents.
 4.  If a mapped skill is missing, continue with best fallback and state it.
 
+After the skill log is complete, append the Context Budget block in the same response/update.
+
 ## 4) Request Classifier
 
 1. Question/explanation requests: answer directly.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/rules/.windsurfrules

@@ -32,11 +32,39 @@ Before starting ANY task, the agent MUST:
 
 ## 3) Skill Loading Policy
 
+## MCP-first Skill Discovery Order (Required)
+
+1. Use `skill_search` first to narrow candidate skills.
+2. Use `skill_browse_category` second to inspect category-level candidates.
+3. Use `skill_get` only for final selected skills that must be loaded.
+4. Keep pointer-first flow; avoid loading full skill text prematurely.
+
+## Skill Log Completion Block (Required)
+
+After finishing skill selection/loading, publish:
+
+- `selected_skills`: skill IDs selected for the task
+- `loaded_skills`: skill IDs loaded via `skill_get`
+- `skipped_skills`: considered but not loaded
+
+## Context Budget Block (Required, Estimated)
+
+Immediately after the Skill Log block, publish estimated budget fields:
+
+- `full_catalog_est_tokens`
+- `loaded_est_tokens`
+- `estimated_savings_tokens`
+- `estimated_savings_percent`
+
+Mark all context/token values as deterministic estimates (not provider metering).
+
 1.  Load only skills needed for the active request.
 2.  Prefer progressive disclosure: start from `SKILL.md`, then specific sections.
 3.  Keep context lean; avoid loading unrelated skill documents.
 4.  If a mapped skill is missing, continue with best fallback and state it.
 
+After the skill log is complete, append the Context Budget block in the same response/update.
+
 ## 4) Request Classifier
 
 1. Question/explanation requests: answer directly.