@cstack-protocol/pingala 1.0.0

package/src/tools/get-governance-context.ts

@@ -0,0 +1,69 @@
+import { Governor } from "../core/governor.js";
+import { ConvexHttpClient } from "convex/browser";
+
+const CONVEX_URL = process.env.CONVEX_URL || "https://impressive-hamster-318.convex.cloud";
+const client = new ConvexHttpClient(CONVEX_URL);
+
+export const getGovernanceContextTool = {
+    name: "get_governance_context",
+    description: "Returns current stack state for context injection. Use this before making AI suggestions to ensure compliance with user's constraints.",
+    schema: {},
+    handler: async () => {
+        const apiKey = process.env.CSTACK_API_KEY;
+        let context;
+
+        if (apiKey) {
+            try {
+                // Try to fetch latest stack from Convex
+                const latest = await client.query("stacks:getLatestStack" as any, { operatorHash: apiKey });
+                if (latest) {
+                    // Reconstruct hierarchical context from stored stack
+                    const tools = latest.tree as any[];
+
+                    // Group tools by their functional slots (functionId)
+                    const slots: Record<string, any[]> = {};
+                    tools.forEach(t => {
+                        const fid = t.functionId || "Unclassified";
+                        if (!slots[fid]) slots[fid] = [];
+                        slots[fid].push(t);
+                    });
+
+                    context = {
+                        core_geometry: latest.geometry.core,
+                        contextual_geometry: latest.geometry.contexts,
+                        functional_slots: Object.entries(slots).map(([id, tools]) => ({
+                            id,
+                            primary_role: tools.find(t => t.role === "Anchor" || t.role === "Active")?.role || "Supporting",
+                            tools: tools.map(t => ({
+                                name: t.name,
+                                role: t.role,
+                                context: t.context,
+                                is_parent: t.is_parent,
+                                is_substack: t.is_substack,
+                                parent_name: t.parent_name
+                            }))
+                        })),
+                        source: "CSTACK API (Convex)"
+                    };
+                }
+            } catch (e) {
+                console.error("Failed to fetch stack from Convex:", e);
+            }
+        }
+
+        // Fallback to local Governor logic
+        if (!context) {
+            context = {
+                ...Governor.getGovernanceContext(),
+                source: "Local (Fallback)"
+            };
+        }
+
+        return {
+            content: [{
+                type: "text" as const,
+                text: JSON.stringify(context, null, 2)
+            }]
+        };
+    }
+};

package/src/tools/validate-stack-change.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { Governor, type ProposedChange } from "../core/governor.js";
+import { flushTelemetry } from "../core/sdk-adapter.js";
+import { ConvexHttpClient } from "convex/browser";
+
+const CONVEX_URL = process.env.CONVEX_URL || "https://impressive-hamster-318.convex.cloud";
+const client = new ConvexHttpClient(CONVEX_URL);
+
+export const validateStackChangeTool = {
+    name: "validate_stack_change",
+    description: "Validates any proposed stack change against 5:3:1 Protocol, CSI thresholds, and maturity gates. Call this BEFORE suggesting tool additions, role changes, or anchor modifications.",
+    schema: {
+        change_type: z.enum(["add_tool", "remove_tool", "change_role", "change_anchor"]).describe("Type of stack modification"),
+        tool_name: z.string().describe("Name of the tool being added/modified"),
+        proposed_role: z.enum(["Anchor", "Active", "Supporting"]).optional().describe("Intended role in 5:3:1 hierarchy"),
+        function_id: z.string().optional().describe("The functional node/Bāguà room this tool belongs to (e.g., 'browser', 'comms')"),
+        contexts: z.array(z.string()).optional().describe("Contexts where this tool is used (e.g., ['mobile', 'desktop'])"),
+        is_adapter: z.boolean().optional().describe("Set to true if this is a contextual window into another node"),
+        replaces_existing: z.boolean().optional().describe("Whether this replaces an existing tool"),
+        replaced_tool: z.string().optional().describe("Name of tool being replaced (if applicable)"),
+        justification: z.string().optional().describe("User's reasoning for the change")
+    },
+    handler: async (args: {
+        change_type: 'add_tool' | 'remove_tool' | 'change_role' | 'change_anchor';
+        tool_name: string;
+        proposed_role?: 'Anchor' | 'Active' | 'Supporting';
+        function_id?: string;
+        contexts?: string[];
+        is_adapter?: boolean;
+        replaces_existing?: boolean;
+        replaced_tool?: string;
+        justification?: string;
+    }) => {
+        const apiKey = process.env.CSTACK_API_KEY;
+        let currentStack: any[] | undefined;
+
+        if (apiKey) {
+            try {
+                const latest = await client.query("stacks:getLatestStack" as any, { operatorHash: apiKey });
+                if (latest) {
+                    currentStack = latest.tree;
+                }
+            } catch (e) {
+                console.error("Failed to fetch stack for change validation:", e);
+            }
+        }
+
+        // Record validation for Decision Provenance
+        Governor.recordValidation(!!args.justification);
+
+        const result = Governor.validateStackChange({
+            ...args,
+            type: args.change_type,
+            functionId: args.function_id,
+            isAdapter: args.is_adapter
+        }, currentStack);
+
+        // Background flush
+        flushTelemetry().catch((err: any) => console.error("Telemetry sync failed", err));
+
+        return {
+            content: [{
+                type: "text" as const,
+                text: JSON.stringify({
+                    ...result,
+                    source: currentStack ? "CSTACK API (Convex)" : "Local (Fallback)"
+                }, null, 2)
+            }]
+        };
+    }
+};

package/src/types.d.ts

@@ -0,0 +1,2 @@
+declare module 'express';
+declare module 'cors';

package/tsconfig.json

@@ -0,0 +1,40 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    // "rootDir": "./src",
+    "outDir": "./build",
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "NodeNext",
+    "target": "es2022",
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "removeComments": true,
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+    // Recommended Options
+    "strict": true,
+    "skipLibCheck": true,
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "baseUrl": "."
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/vercel.json

@@ -0,0 +1,15 @@
+{
+    "version": 2,
+    "builds": [
+        {
+            "src": "src/index.ts",
+            "use": "@vercel/node"
+        }
+    ],
+    "routes": [
+        {
+            "src": "/(.*)",
+            "dest": "src/index.ts"
+        }
+    ]
+}