get_session_snapshot

Instructions

Implementation Reference

• src/tools/snapshot.ts:41-162 (handler)

  Main handler function that collects and returns a full diagnostic snapshot of the dev environment: framework detection, runtimes, running services, recent errors, git state, and diagnosis.

  export async function getSessionSnapshot(cwd: string): Promise<SessionSnapshot> {
    const baseProject = path.basename(cwd);
    try {
      const frameworkPromise = detectFramework(cwd);
      const runtimesPromise = detectRuntimes(cwd);
      const servicesPromise = frameworkPromise.then((framework) =>
        getRunningServices(framework.expectedPorts)
      );
      const errorsPromise = frameworkPromise.then((framework) =>
        getRecentErrors(cwd, framework.logPaths, 50)
      );
  
      const [frameworkResult, runtimesResult, servicesResult, errorsResult] =
        await Promise.allSettled([
          frameworkPromise,
          runtimesPromise,
          servicesPromise,
          errorsPromise,
        ]);
  
      const framework =
        frameworkResult.status === "fulfilled"
          ? frameworkResult.value
          : { framework: "unknown", expectedPorts: [], logPaths: ["logs/"] };
  
      const runtimes =
        runtimesResult.status === "fulfilled"
          ? runtimesResult.value
          : { node: null, python: null, go: null, packageManager: "unknown" };
  
      const services =
        servicesResult.status === "fulfilled"
          ? servicesResult.value
          : { running: [], expected_but_missing: [] };
  
      const recentErrors = errorsResult.status === "fulfilled" ? errorsResult.value : [];
  
      let branch: string | null = null;
      let uncommittedFiles = 0;
      let lastCommit: string | null = null;
  
      try {
        const git = simpleGit(cwd);
        const [statusResult, logResult] = await Promise.all([
          git.status(),
          git.log({ maxCount: 1 }),
        ]);
  
        branch = statusResult.current || null;
        uncommittedFiles = statusResult.files.length;
        lastCommit = logResult.latest?.hash ?? null;
      } catch {
        branch = null;
        uncommittedFiles = 0;
        lastCommit = null;
      }
  
      const diagnosis = diagnose({
        running: services.running.map((service) => ({
          port: service.port,
          name: service.name,
        })),
        expected_but_missing: services.expected_but_missing,
        recentErrors: recentErrors.map((error) => ({
          level: error.level,
          message: error.message,
        })),
        framework: framework.framework,
      });
  
      const result: SessionSnapshot = {
        diagnosis,
        session: {
          project: baseProject,
          framework: framework.framework,
          branch,
          uncommitted_files: uncommittedFiles,
          last_commit: lastCommit,
        },
        services: {
          running: services.running.map((service) => ({
            port: service.port,
            name: service.name,
          })),
          expected_but_missing: services.expected_but_missing,
        },
        recent_errors: recentErrors.map((error) => ({
          time: error.time,
          level: error.level,
          message: error.message,
        })),
        env: {
          node: runtimes.node,
          python: runtimes.python,
          go: runtimes.go,
          package_manager: runtimes.packageManager,
        },
      };
      return result;
    } catch {
      const result: SessionSnapshot = {
        diagnosis: {
          health: "degraded",
          primary_issue: "Unable to determine environment state",
          secondary_signals: [],
          suggested_action: "Try running get_session_snapshot again",
          confidence: "low",
        },
        session: {
          project: path.basename(cwd),
          framework: "unknown",
          branch: null,
          uncommitted_files: 0,
          last_commit: null,
        },
        services: { running: [], expected_but_missing: [] },
        recent_errors: [],
        env: { node: null, python: null, go: null, package_manager: "unknown" },
      };
      return result;
    }
  }

• src/tools/snapshot.ts:9-39 (schema)

  Type definition for the SessionSnapshot return type, with nested interfaces for diagnosis, session, services, recent_errors, and env.

  export interface SessionSnapshot {
    diagnosis: {
      health: "healthy" | "degraded" | "broken";
      primary_issue: string | null;
      secondary_signals: string[];
      suggested_action: string | null;
      confidence: "high" | "medium" | "low";
    };
    session: {
      project: string;
      framework: string;
      branch: string | null;
      uncommitted_files: number;
      last_commit: string | null;
    };
    services: {
      running: Array<{ port: number; name: string }>;
      expected_but_missing: number[];
    };
    recent_errors: Array<{
      time: string;
      level: string;
      message: string;
    }>;
    env: {
      node: string | null;
      python: string | null;
      go: string | null;
      package_manager: string;
    };
  }

• src/index.ts:28-72 (registration)

  Registration of the tool 'get_session_snapshot' with description and input schema (cwd string parameter).

    tools: [
      {
        name: "get_session_snapshot",
        description:
          "Returns a real-time diagnostic snapshot of the current dev environment. Includes health diagnosis, running services, recent errors, git state, and environment info. Call this first to orient yourself in the user's dev session.",
        inputSchema: {
          type: "object",
          properties: {
            cwd: {
              type: "string",
            },
          },
        },
      },
      {
        name: "get_recent_errors",
        description:
          "Returns recent ERROR and WARN log entries from the detected project's log files. Deduped, timestamped, secrets redacted. Defaults to last 50 lines.",
        inputSchema: {
          type: "object",
          properties: {
            cwd: {
              type: "string",
            },
            limit: {
              type: "number",
            },
          },
        },
      },
      {
        name: "get_running_services",
        description:
          "Lists processes running on common dev ports (3000, 4000, 5173, 8080 etc). Shows what is running and what is expected but missing.",
        inputSchema: {
          type: "object",
          properties: {
            cwd: {
              type: "string",
            },
          },
        },
      },
    ],
  };

• src/index.ts:78-102 (handler)

  The call handler in index.ts that dispatches to getSessionSnapshot when the tool is invoked, with error handling.

  if (toolName === "get_session_snapshot") {
    try {
      const args = request.params.arguments as { cwd?: string } | undefined;
      const cwd = args?.cwd ?? process.cwd();
      const result = await getSessionSnapshot(cwd);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: `Failed to get session snapshot: ${String(error)}`,
            }),
          },
        ],
      };
    }

• src/diagnosis/engine.ts:19-103 (helper)

  Diagnosis engine used by getSessionSnapshot to determine health status (healthy/degraded/broken) based on running services, port conflicts, and recent errors.

  export function diagnose(input: DiagnosisInput): DiagnosisResult {
    const running = input.running ?? [];
    const missing = input.expected_but_missing ?? [];
    const recentErrors = input.recentErrors ?? [];
  
    const hasAddrInUse = recentErrors.some((error) =>
      error.message.includes("EADDRINUSE")
    );
    const errorEntries = recentErrors.filter(
      (error) => error.level.toUpperCase() === "ERROR"
    );
    const hasErrorLevelEntries = errorEntries.length > 0;
  
    // Pattern 1 — Port conflict (broken)
    if (hasAddrInUse && missing.length > 0) {
      return {
        health: "broken",
        primary_issue: "Port conflict — dev server cannot start",
        secondary_signals: missing.map(
          (port) => `Port ${port} is already in use`
        ),
        suggested_action:
          "Kill the process using that port or change your dev server port",
        confidence: "high",
      };
    }
  
    // Pattern 2 — Dev server crashed (broken)
    if (missing.length > 0 && hasErrorLevelEntries && !hasAddrInUse) {
      return {
        health: "broken",
        primary_issue: "Dev server appears to have crashed",
        secondary_signals: errorEntries.slice(0, 3).map((error) => error.message),
        suggested_action: "Check the error logs and restart your dev server",
        confidence: "medium",
      };
    }
  
    // Pattern 3 — Silent failure (degraded)
    if (missing.length > 0 && recentErrors.length === 0) {
      return {
        health: "degraded",
        primary_issue: "Expected service not running — no recent logs found",
        secondary_signals: missing.map(
          (port) => `Port ${port} expected but nothing is listening`
        ),
        suggested_action: "Start your dev server",
        confidence: "low",
      };
    }
  
    // Pattern 4 — Errors but running (degraded)
    if (running.length > 0 && hasErrorLevelEntries) {
      return {
        health: "degraded",
        primary_issue: "Errors detected but services are still running",
        secondary_signals: errorEntries.slice(0, 3).map((error) => error.message),
        suggested_action:
          "Review the recent errors — the server is up but something is failing",
        confidence: "medium",
      };
    }
  
    // Pattern 5 — Healthy (healthy)
    if (running.length > 0 && recentErrors.length === 0 && missing.length === 0) {
      return {
        health: "healthy",
        primary_issue: null,
        secondary_signals: running.map(
          (service) => `Port ${service.port}: ${service.name}`
        ),
        suggested_action: null,
        confidence: "high",
      };
    }
  
    // Default fallback
    return {
      health: "degraded",
      primary_issue: "Unable to determine environment state",
      secondary_signals: [],
      suggested_action: "Try running get_session_snapshot again",
      confidence: "low",
    };
  }