get_call_stack

Instructions

Implementation Reference

• src/server.ts:256-278 (registration)

  Tool registration for 'get_call_stack' with input schema definition (session_id required, include_async optional boolean).

  {
    name: 'get_call_stack',
    description:
      'Retrieves the current call stack when execution is paused. ' +
      'Shows the chain of function calls that led to the current location, ' +
      'including function names, file locations, and scope information. ' +
      'If source maps are available, original source locations are included.',
    inputSchema: {
      type: 'object',
      properties: {
        session_id: {
          type: 'string',
          description: 'ID of the debugging session. The session must be paused.',
        },
        include_async: {
          type: 'boolean',
          description:
            'Whether to include asynchronous stack traces (Promise chains, async/await). Defaults to true.',
        },
      },
      required: ['session_id'],
    },
  },

• src/server.ts:751-801 (handler)

  Handler implementation for 'get_call_stack' tool call. Validates params via Zod, calls sessionManager.getCallStack(), and formats the response with call frames (ID, function name, generated/original location, scope chain) and optional async stack trace.

  case 'get_call_stack': {
    const params = z
      .object({
        session_id: z.string(),
        include_async: z.boolean().optional(),
      })
      .parse(args);
  
    const {callFrames, asyncStackTrace} = sessionManager.getCallStack(
      params.session_id,
      params.include_async ?? true
    );
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              call_frames: callFrames.map((frame) => ({
                call_frame_id: frame.callFrameId,
                function_name: frame.functionName,
                generated_location: {
                  script_id: frame.generatedLocation.scriptId,
                  line_number: frame.generatedLocation.lineNumber,
                  column_number: frame.generatedLocation.columnNumber,
                },
                original_location: frame.originalLocation
                  ? {
                      source_url: frame.originalLocation.sourceUrl,
                      line_number: frame.originalLocation.lineNumber,
                      column_number: frame.originalLocation.columnNumber,
                      function_name: frame.originalLocation.functionName,
                    }
                  : undefined,
                scope_chain: frame.scopeChain.map((scope) => ({
                  type: scope.type,
                  name: scope.name,
                })),
              })),
              async_stack_trace: asyncStackTrace
                ? {
                    description: asyncStackTrace.description,
                  }
                : undefined,
            },
            null,
            2
          ),
        },
      ],

• src/session-manager.ts:339-357 (handler)

  SessionManager.getCallStack() - retrieves the enriched call stack for a paused session. Calls enrichCallFrames() and optionally includes asyncStackTrace from paused state.

  getCallStack(
    sessionId: string,
    includeAsync = true
  ): {
    callFrames: EnrichedCallFrame[];
    asyncStackTrace?: Protocol.Runtime.StackTrace;
  } {
    const session = this.getSession(sessionId);
    this.ensurePaused(session);
  
    const enrichedFrames = this.enrichCallFrames(session);
  
    return {
      callFrames: enrichedFrames,
      asyncStackTrace: includeAsync
        ? session.pausedState?.asyncStackTrace
        : undefined,
    };
  }

• src/session-manager.ts:809-843 (helper)

  EnrichCallFrames() private helper - maps raw CDP call frames to EnrichedCallFrame objects, resolving original source locations via sourceMapManager.

  private enrichCallFrames(session: ManagedSession): EnrichedCallFrame[] {
    if (!session.pausedState) return [];
  
    return session.pausedState.callFrames.map((frame) => {
      const enriched: EnrichedCallFrame = {
        callFrameId: frame.callFrameId,
        functionName: frame.functionName,
        generatedLocation: {
          scriptId: frame.location.scriptId,
          lineNumber: frame.location.lineNumber,
          columnNumber: frame.location.columnNumber ?? 0,
        },
        scopeChain: frame.scopeChain,
        this: frame.this,
      };
  
      // Try to map to original location.
      const original = session.sourceMapManager.getOriginalLocation(
        frame.location.scriptId,
        frame.location.lineNumber + 1, // source-map uses 1-based lines.
        frame.location.columnNumber ?? 0
      );
  
      if (original) {
        enriched.originalLocation = {
          sourceUrl: original.source,
          lineNumber: original.line ?? 0,
          columnNumber: original.column ?? 0,
          functionName: original.name ?? undefined,
        };
      }
  
      return enriched;
    });
  }

• src/types.ts:107-123 (schema)

  EnrichedCallFrame interface type definition, defining the structure of each call frame returned by get_call_stack.

  export interface EnrichedCallFrame {
    callFrameId: string;
    functionName: string;
    generatedLocation: {
      scriptId: string;
      lineNumber: number;
      columnNumber: number;
    };
    originalLocation?: {
      sourceUrl: string;
      lineNumber: number;
      columnNumber: number;
      functionName?: string;
    };
    scopeChain: Protocol.Debugger.Scope[];
    this: Protocol.Runtime.RemoteObject;
  }