triagent 0.1.0-alpha1

package/src/mastra/agents/debugger.ts

@@ -0,0 +1,176 @@
+import { Agent } from "@mastra/core/agent";
+import { z } from "zod";
+import { kubectlTool } from "../tools/kubectl.js";
+import { gitTool } from "../tools/git.js";
+import { filesystemTool } from "../tools/filesystem.js";
+import type { Config } from "../../config.js";
+
+const DEBUGGER_INSTRUCTIONS = `You are an expert Kubernetes debugging agent named Triagent. Your role is to investigate and diagnose issues in Kubernetes clusters by analyzing resources, logs, code, and git history.
+
+## Your Capabilities
+
+1. **Kubernetes Inspection** (kubectl tool):
+   - Get resource status (pods, deployments, services, configmaps)
+   - Describe resources for detailed information
+   - Fetch container logs
+   - Check resource usage (top)
+   - Review cluster events
+
+2. **Code Analysis** (filesystem tool):
+   - Read source code files
+   - List directory structures
+   - Search for patterns in code
+
+3. **Git History** (git tool):
+   - View recent commits
+   - Compare changes between commits
+   - Show specific commit details
+   - Blame files to find who changed what
+
+## Investigation Process
+
+When given an incident, follow this systematic approach:
+
+1. **Understand the Issue**: Parse the incident description to identify:
+   - What service/component is affected
+   - What symptoms are being observed
+   - When the issue started (if known)
+
+2. **Check Cluster State**:
+   - Get pod status for affected services
+   - Check for recent events
+   - Look at resource usage
+
+3. **Analyze Logs**:
+   - Fetch logs from affected pods
+   - Look for errors, exceptions, or unusual patterns
+
+4. **Investigate Recent Changes**:
+   - Check git log for recent commits
+   - Review diffs of suspicious changes
+   - Correlate timing with when issues started
+
+5. **Examine Code**:
+   - Read relevant configuration files
+   - Check application code if needed
+   - Look for misconfigurations
+
+6. **Synthesize Findings**:
+   - Identify the root cause
+   - List affected resources
+   - Provide actionable recommendations
+
+## Output Format
+
+Always provide your findings in a clear, structured format:
+- **Summary**: Brief overview of the issue
+- **Root Cause**: The identified cause of the problem
+- **Evidence**: Specific data that supports your conclusion
+- **Affected Resources**: List of impacted K8s resources
+- **Recent Changes**: Relevant commits that might be related
+- **Recommendations**: Specific steps to remediate the issue
+
+## Important Guidelines
+
+- Be thorough but efficient - don't run unnecessary commands
+- Focus on actionable insights
+- If unsure, state your confidence level
+- Prioritize quick wins that can restore service
+- Consider both application and infrastructure issues`;
+
+export const InvestigationResultSchema = z.object({
+  summary: z.string().describe("Brief overview of the investigation"),
+  rootCause: z.string().describe("Identified root cause of the issue"),
+  confidence: z
+    .enum(["high", "medium", "low"])
+    .describe("Confidence level in the diagnosis"),
+  evidence: z
+    .array(z.string())
+    .describe("Specific evidence supporting the diagnosis"),
+  affectedResources: z
+    .array(
+      z.object({
+        type: z.string(),
+        name: z.string(),
+        namespace: z.string().optional(),
+        status: z.string(),
+      })
+    )
+    .describe("List of affected Kubernetes resources"),
+  recentChanges: z
+    .array(
+      z.object({
+        commit: z.string(),
+        message: z.string(),
+        author: z.string(),
+        relevance: z.string(),
+      })
+    )
+    .optional()
+    .describe("Relevant recent git commits"),
+  recommendations: z
+    .array(
+      z.object({
+        priority: z.enum(["critical", "high", "medium", "low"]),
+        action: z.string(),
+        details: z.string().optional(),
+      })
+    )
+    .describe("Recommended actions to resolve the issue"),
+});
+
+export type InvestigationResult = z.infer<typeof InvestigationResultSchema>;
+
+export function createDebuggerAgent(config: Config) {
+  // Construct model string based on provider
+  const modelString = `${config.aiProvider}/${config.aiModel}`;
+
+  return new Agent({
+    id: "kubernetes-debugger",
+    name: "Kubernetes Debugger",
+    instructions: DEBUGGER_INSTRUCTIONS,
+    model: modelString as any, // Mastra handles model routing
+    tools: {
+      kubectl: kubectlTool,
+      git: gitTool,
+      filesystem: filesystemTool,
+    },
+  });
+}
+
+export interface IncidentInput {
+  title: string;
+  description: string;
+  severity?: "critical" | "warning" | "info";
+  labels?: Record<string, string>;
+}
+
+export function buildIncidentPrompt(incident: IncidentInput): string {
+  const parts = [
+    `# Incident Report`,
+    ``,
+    `**Title**: ${incident.title}`,
+    ``,
+    `**Description**: ${incident.description}`,
+  ];
+
+  if (incident.severity) {
+    parts.push(``, `**Severity**: ${incident.severity}`);
+  }
+
+  if (incident.labels && Object.keys(incident.labels).length > 0) {
+    parts.push(``, `**Labels**:`);
+    for (const [key, value] of Object.entries(incident.labels)) {
+      parts.push(`- ${key}: ${value}`);
+    }
+  }
+
+  parts.push(
+    ``,
+    `---`,
+    ``,
+    `Please investigate this incident and provide your findings.`
+  );
+
+  return parts.join("\n");
+}

package/src/mastra/index.ts

@@ -0,0 +1,36 @@
+import { Mastra } from "@mastra/core";
+import { createDebuggerAgent, buildIncidentPrompt, InvestigationResultSchema } from "./agents/debugger.js";
+import type { Config } from "../config.js";
+
+let mastraInstance: Mastra | null = null;
+
+export function createMastraInstance(config: Config): Mastra {
+  if (mastraInstance) {
+    return mastraInstance;
+  }
+
+  const debuggerAgent = createDebuggerAgent(config);
+
+  mastraInstance = new Mastra({
+    agents: {
+      debugger: debuggerAgent,
+    },
+  });
+
+  return mastraInstance;
+}
+
+export function getMastra(): Mastra {
+  if (!mastraInstance) {
+    throw new Error("Mastra not initialized. Call createMastraInstance first.");
+  }
+  return mastraInstance;
+}
+
+export function getDebuggerAgent() {
+  const mastra = getMastra();
+  return mastra.getAgent("debugger");
+}
+
+export { createDebuggerAgent, buildIncidentPrompt, InvestigationResultSchema };
+export type { IncidentInput, InvestigationResult } from "./agents/debugger.js";

package/src/mastra/tools/filesystem.ts

@@ -0,0 +1,129 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { readFile, listDir, execCommand } from "../../sandbox/bashlet.js";
+
+const ALLOWED_OPERATIONS = ["read", "list", "search"] as const;
+
+const FilesystemInputSchema = z.object({
+  operation: z.enum(ALLOWED_OPERATIONS).describe("The file operation to perform"),
+  path: z
+    .string()
+    .describe(
+      "File or directory path relative to /workspace (the mounted codebase)"
+    ),
+  pattern: z
+    .string()
+    .optional()
+    .describe("Search pattern for 'search' operation (grep-compatible regex)"),
+  maxLines: z
+    .number()
+    .optional()
+    .describe("Maximum lines to return for read operation (default: 500)"),
+});
+
+// Output type (no schema validation to allow error returns)
+interface FilesystemOutput {
+  success: boolean;
+  content?: string;
+  entries?: string[];
+  error?: string;
+}
+
+function sanitizePath(path: string): string {
+  // Ensure path stays within /workspace
+  const cleanPath = path
+    .replace(/\.\./g, "") // Remove parent directory references
+    .replace(/^\/+/, "") // Remove leading slashes
+    .replace(/\/+/g, "/"); // Normalize multiple slashes
+
+  return `/workspace/${cleanPath}`;
+}
+
+export const filesystemTool = createTool({
+  id: "filesystem",
+  description: `Read files and list directories in the codebase.
+Available operations:
+- read: Read file contents (max 500 lines by default)
+- list: List directory contents
+- search: Search for pattern in files using grep
+
+All paths are relative to the codebase root (/workspace).
+Examples:
+- Read a file: { operation: "read", path: "src/index.ts" }
+- List directory: { operation: "list", path: "src/api" }
+- Search for pattern: { operation: "search", path: "src", pattern: "async function" }
+- Read with line limit: { operation: "read", path: "package.json", maxLines: 100 }`,
+
+  inputSchema: FilesystemInputSchema,
+
+  execute: async (inputData): Promise<FilesystemOutput> => {
+    const { operation, path, pattern, maxLines = 500 } = inputData;
+    const safePath = sanitizePath(path);
+
+    try {
+      switch (operation) {
+        case "read": {
+          const content = await readFile(safePath);
+          const lines = content.split("\n");
+          const truncated =
+            lines.length > maxLines
+              ? lines.slice(0, maxLines).join("\n") +
+                `\n\n... [Truncated: showing ${maxLines} of ${lines.length} lines]`
+              : content;
+
+          return {
+            success: true,
+            content: truncated,
+          };
+        }
+
+        case "list": {
+          const entries = await listDir(safePath);
+          return {
+            success: true,
+            entries,
+          };
+        }
+
+        case "search": {
+          if (!pattern) {
+            return {
+              success: false,
+              error: "Pattern is required for search operation",
+            };
+          }
+
+          // Use grep for searching
+          const grepCommand = `grep -rn "${pattern.replace(/"/g, '\\"')}" "${safePath}" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.json" --include="*.yaml" --include="*.yml" --include="*.md" | head -100`;
+
+          const result = await execCommand(grepCommand);
+
+          if (result.exitCode !== 0 && result.exitCode !== 1) {
+            // grep returns 1 when no matches found
+            return {
+              success: false,
+              error: result.stderr || "Search failed",
+            };
+          }
+
+          return {
+            success: true,
+            content:
+              result.stdout || "No matches found",
+          };
+        }
+
+        default:
+          return {
+            success: false,
+            error: `Unknown operation: ${operation}`,
+          };
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  },
+});

package/src/mastra/tools/git.ts

@@ -0,0 +1,83 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { execCommand } from "../../sandbox/bashlet.js";
+
+const ALLOWED_COMMANDS = ["log", "diff", "show", "blame"] as const;
+
+const GitInputSchema = z.object({
+  command: z.enum(ALLOWED_COMMANDS).describe("The git command to run (read-only)"),
+  args: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Command arguments (e.g., ['--oneline', '-n', '20'] for log, ['HEAD~5..HEAD'] for diff)"
+    ),
+  path: z.string().optional().describe("File or directory path to operate on"),
+});
+
+// Output type (no schema validation to allow error returns)
+interface GitOutput {
+  success: boolean;
+  output: string;
+  error?: string;
+}
+
+export const gitTool = createTool({
+  id: "git",
+  description: `Execute read-only git commands to analyze repository history and changes.
+Available commands: ${ALLOWED_COMMANDS.join(", ")}.
+Use this to investigate recent changes that might have caused issues.
+Examples:
+- Recent commits: { command: "log", args: ["--oneline", "-n", "20"] }
+- Changes in last 5 commits: { command: "diff", args: ["HEAD~5..HEAD"] }
+- Show specific commit: { command: "show", args: ["abc123"] }
+- Blame a file: { command: "blame", path: "src/app.ts" }
+- Log for specific file: { command: "log", args: ["-p", "-n", "5", "--"], path: "src/api/handler.ts" }`,
+
+  inputSchema: GitInputSchema,
+
+  execute: async (inputData): Promise<GitOutput> => {
+    const { command, args, path } = inputData;
+
+    // Build git command
+    const parts = ["git", command];
+
+    if (args && args.length > 0) {
+      parts.push(...args);
+    }
+
+    if (path) {
+      // Ensure path separator for git commands that need it
+      if (command === "log" && !args?.includes("--")) {
+        parts.push("--");
+      }
+      parts.push(path);
+    }
+
+    const fullCommand = parts.join(" ");
+
+    try {
+      const result = await execCommand(fullCommand);
+
+      if (result.exitCode !== 0) {
+        return {
+          success: false,
+          output: "",
+          error: result.stderr || `Command failed with exit code ${result.exitCode}`,
+        };
+      }
+
+      return {
+        success: true,
+        output: result.stdout,
+        error: result.stderr || undefined,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  },
+});

package/src/mastra/tools/kubectl.ts

@@ -0,0 +1,107 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { execCommand } from "../../sandbox/bashlet.js";
+
+const ALLOWED_COMMANDS = ["get", "describe", "logs", "top", "events"] as const;
+
+const KubectlInputSchema = z.object({
+  command: z.enum(ALLOWED_COMMANDS).describe("The kubectl command to run"),
+  resource: z
+    .string()
+    .optional()
+    .describe(
+      "Resource type (e.g., pods, deployments, services, configmaps, secrets)"
+    ),
+  name: z.string().optional().describe("Specific resource name"),
+  namespace: z
+    .string()
+    .optional()
+    .describe("Kubernetes namespace (defaults to current context namespace)"),
+  flags: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Additional flags (e.g., ['-o', 'yaml'], ['--tail', '100'], ['-l', 'app=myapp'])"
+    ),
+});
+
+// Output type (no schema validation to allow error returns)
+interface KubectlOutput {
+  success: boolean;
+  output: string;
+  error?: string;
+}
+
+function filterSensitiveData(output: string): string {
+  // Redact potential secrets, tokens, and passwords
+  return output
+    .replace(
+      /(password|secret|token|key|credential)[\s:=]+["']?[^\s"'\n]+["']?/gi,
+      "$1: [REDACTED]"
+    )
+    .replace(/Bearer\s+[^\s]+/gi, "Bearer [REDACTED]")
+    .replace(/-----BEGIN[^-]+-----[\s\S]*?-----END[^-]+-----/g, "[REDACTED CERTIFICATE/KEY]");
+}
+
+export const kubectlTool = createTool({
+  id: "kubectl",
+  description: `Execute kubectl commands to inspect Kubernetes resources.
+Available commands: ${ALLOWED_COMMANDS.join(", ")}.
+Use this to get information about pods, deployments, services, logs, and cluster events.
+Examples:
+- Get all pods: { command: "get", resource: "pods", flags: ["-A"] }
+- Get pod logs: { command: "logs", name: "my-pod", namespace: "default", flags: ["--tail", "100"] }
+- Describe deployment: { command: "describe", resource: "deployment", name: "my-app" }
+- Get events: { command: "events", namespace: "production", flags: ["--sort-by", ".lastTimestamp"] }`,
+
+  inputSchema: KubectlInputSchema,
+
+  execute: async (inputData): Promise<KubectlOutput> => {
+    const { command, resource, name, namespace, flags } = inputData;
+
+    // Build kubectl command
+    const parts = ["kubectl", command];
+
+    if (resource) {
+      parts.push(resource);
+    }
+
+    if (name) {
+      parts.push(name);
+    }
+
+    if (namespace) {
+      parts.push("-n", namespace);
+    }
+
+    if (flags && flags.length > 0) {
+      parts.push(...flags);
+    }
+
+    const fullCommand = parts.join(" ");
+
+    try {
+      const result = await execCommand(fullCommand);
+
+      if (result.exitCode !== 0) {
+        return {
+          success: false,
+          output: "",
+          error: result.stderr || `Command failed with exit code ${result.exitCode}`,
+        };
+      }
+
+      return {
+        success: true,
+        output: filterSensitiveData(result.stdout),
+        error: result.stderr ? filterSensitiveData(result.stderr) : undefined,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  },
+});

package/src/sandbox/bashlet.ts

@@ -0,0 +1,151 @@
+import { Bashlet } from "@bashlet/sdk";
+import { $ } from "bun";
+import { readFile as fsReadFile, readdir } from "fs/promises";
+import type { Config } from "../config.js";
+
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface SandboxOptions {
+  codebasePath: string;
+  kubeConfigPath: string;
+  timeout?: number;
+  useHost?: boolean;
+}
+
+let bashletInstance: Bashlet | null = null;
+let hostMode = false;
+let hostWorkdir = "./";
+
+export function createSandbox(options: SandboxOptions): void {
+  hostMode = options.useHost ?? false;
+  hostWorkdir = options.codebasePath;
+
+  if (hostMode) {
+    return;
+  }
+
+  if (bashletInstance) {
+    return;
+  }
+
+  bashletInstance = new Bashlet({
+    mounts: [
+      { hostPath: options.codebasePath, guestPath: "/workspace" },
+      { hostPath: options.kubeConfigPath, guestPath: "/root/.kube" },
+    ],
+    workdir: "/workspace",
+    timeout: options.timeout || 120,
+    envVars: [
+      { key: "KUBECONFIG", value: "/root/.kube/config" },
+      { key: "HOME", value: "/root" },
+    ],
+  });
+}
+
+export function isHostMode(): boolean {
+  return hostMode;
+}
+
+export async function execCommand(command: string): Promise<CommandResult> {
+  if (hostMode) {
+    try {
+      const result = await $`sh -c ${command}`.cwd(hostWorkdir).nothrow().quiet();
+      return {
+        stdout: result.stdout.toString(),
+        stderr: result.stderr.toString(),
+        exitCode: result.exitCode,
+      };
+    } catch (error) {
+      return {
+        stdout: "",
+        stderr: error instanceof Error ? error.message : String(error),
+        exitCode: 1,
+      };
+    }
+  }
+
+  if (!bashletInstance) {
+    throw new Error("Sandbox not initialized. Call createSandbox first.");
+  }
+
+  try {
+    const result = await bashletInstance.exec(command);
+    return {
+      stdout: result.stdout || "",
+      stderr: result.stderr || "",
+      exitCode: result.exitCode ?? 0,
+    };
+  } catch (error) {
+    return {
+      stdout: "",
+      stderr: error instanceof Error ? error.message : String(error),
+      exitCode: 1,
+    };
+  }
+}
+
+export async function readFile(path: string): Promise<string> {
+  if (hostMode) {
+    const fullPath = path.startsWith("/") ? path : `${hostWorkdir}/${path}`;
+    try {
+      return await fsReadFile(fullPath, "utf-8");
+    } catch (error) {
+      throw new Error(
+        `Failed to read file ${path}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  if (!bashletInstance) {
+    throw new Error("Sandbox not initialized. Call createSandbox first.");
+  }
+
+  try {
+    const content = await bashletInstance.readFile(path);
+    return content;
+  } catch (error) {
+    throw new Error(
+      `Failed to read file ${path}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+export async function listDir(path: string): Promise<string[]> {
+  if (hostMode) {
+    const fullPath = path.startsWith("/") ? path : `${hostWorkdir}/${path}`;
+    try {
+      const entries = await readdir(fullPath);
+      return entries;
+    } catch (error) {
+      throw new Error(
+        `Failed to list directory ${path}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  if (!bashletInstance) {
+    throw new Error("Sandbox not initialized. Call createSandbox first.");
+  }
+
+  try {
+    const output = await bashletInstance.listDir(path);
+    return output.split("\n").filter((line) => line.trim().length > 0);
+  } catch (error) {
+    throw new Error(
+      `Failed to list directory ${path}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+export function initSandboxFromConfig(config: Config, useHost: boolean = false): void {
+  createSandbox({
+    codebasePath: config.codebasePath,
+    kubeConfigPath: config.kubeConfigPath,
+    timeout: 120,
+    useHost,
+  });
+}